🚀 ynab-mcp-server

ynab-mcp-server 是一个基于 mcp-framework 构建的模型上下文协议 (MCP) 服务器，专为 YNAB（You Need A Budget）预算工具打造。此 MCP 提供了与你在 https://ynab.com 上设置的 YNAB 预算进行交互的工具。

为了让 AI 能够与该工具交互，你需要获取个人访问令牌，获取地址为：https://api.ynab.com/#personal-access-tokens。当将此 MCP 服务器添加到任何客户端时，你需要提供个人访问令牌作为 YNAB_API_TOKEN。请注意，此令牌绝不会直接发送给 LLM（大语言模型），它会安全地存储在环境变量中，仅用于与 YNAB API 通信。

🚀 快速开始

1. 克隆仓库：

git clone https://github.com/your-repository.git

2. 安装依赖项：

npm install

3. 配置环境变量：

export YNAP_API_TOKEN=your_token_here

4. 运行服务器：

node dist/index.js

✨ 主要特性

• 提供与 YNAB 预算交互的工具，可通过 AI 对话与 YNAB 预算进行交互。
• 支持多种工作流程，如第一次设置、管理超支类别、添加新交易等。
• 提供丰富的工具列表，可对预算、类别等进行管理。

📦 安装指南

指定环境变量

• YNAP_API_TOKEN（必需）：你的 YNAB 个人访问令牌。
• KNOWLEDGE_DIR（可选）：知识文件存储目录，默认为服务器运行所在的 data 目录。
• KNOWLEDGE_FILE（可选）：知识文件名，默认为 server-knowledge.json

📚 详细文档

项目目标

此项目旨在通过 AI 对话与你的 YNAB 预算进行交互，有几个主要的工作流程需要实现。

工作流程

第一次设置

• 提示选择你的预算，从你可用的预算中进行选择。如果你在使用其他工具之前尝试使用此工具，则会触发此提示，要求你设置默认预算。
  • 需要的工具：ListBudgets、SetBudget

管理超支类别

添加新交易

批准交易

检查总月度支出与总收入对比

根据类别目标自动分配资金

当前状态

• 工具列表：
  • ListBudgets：列出所有预算
  • SetBudget：设置默认预算
  • GetCategories：获取预算类别
  • CreateCategory：创建新预算类别
  • UpdateCategory：更新现有预算类别
  • DeleteCategory：删除预算类别
• 下一步计划：
  • 添加交易管理功能（CreateTransaction、UpdateTransaction、DeleteTransaction）
  • 实现预算跟踪和报告

项目结构

.
├── src/
│   ├── tools/           # 工具目录，包含与 YNAB API 交互的工具类
│   │   └── ynabTools.ts
│   └── server.ts       # 主服务器文件
├── package.json        # 项目依赖和脚本
└── README.md           # 项目文档

添加组件

要添加新的功能模块，可按以下步骤操作：

1. 在 src/tools/ 目录下创建新工具类。
2. 实现与 YNAB API 的交互逻辑。
3. 更新服务器文件以加载新工具。

工具开发

工具的基本结构如下：

export class YNABTools {
    private readonly token: string;

    constructor(token: string) {
        this.token = token;
    }

    // 实现具体功能方法
}

发布到 npm

1. 登录到 npm：

npm login

2. 提交版本更新：

npm version patch

3. 发布新版本：

npm publish

其他 MCP 客户端

你可以访问 https://modelcontextprotocol.io/clients 获取更多信息。

学习更多

• MCP 框架 Github
• MCP 框架文档