MCP YNAB Server 使用说明

项目简介

MCP YNAB Server 是一个基于 Model Context Protocol (MCP) 构建的服务器，它充当 Cursor (或其他 MCP 客户端) 与 You Need A Budget (YNAB) API 之间的桥梁。通过此服务器，用户可以在支持 MCP 的编辑器（如 Cursor）中，利用 AI 助手直接访问和操作 YNAB 财务数据。

主要功能点

预算管理: 列出所有预算。
账户管理: 列出指定预算下的所有账户，并获取账户余额。
交易管理: 列出预算或特定账户的交易记录，支持按日期和类型过滤。
类别管理: 列出预算中的所有类别。
预算概览: 获取当前月份的预算概览信息。
类别信息: 获取指定类别的详细信息。
创建交易: 在 YNAB 中创建新的交易记录。

安装步骤

克隆仓库:

git clone https://github.com/Bulletninja/mcp-ynab
cd mcp-ynab

安装依赖:
```
npm install
```
编译代码:
```
npm run build
```

服务器配置

要将 MCP YNAB Server 集成到 MCP 客户端（例如 Cursor），您需要配置客户端的 MCP 设置。以下是 Cursor 客户端的 'mcp.json' 配置文件示例，展示了如何配置 'mcp-ynab' 服务器：

{
  "mcpServers": {
    "mcp-ynab": {
      "command": "node",
      "args": ["<path-to-your-project>/mcp-ynab/dist/server.js"],
      // args:  指向编译后的 server.js 文件路径，请替换为您的实际项目路径
      "cwd": "<path-to-your-project>/mcp-ynab",
      // cwd:  指向项目根目录，请替换为您的实际项目路径
      "enabled": true,
      "env": {
        "YNAB_API_TOKEN": "YOUR_YNAB_TOKEN_HERE"
        // YNAB_API_TOKEN:  您的 YNAB 个人访问令牌，请替换为您的实际令牌
        // 您可以在 YNAB 网站的开发者设置中创建个人访问令牌
      }
    }
  }
}

配置说明:

'"mcpServers"': 定义 MCP 服务器配置的 JSON 对象。
'"mcp-ynab"': 服务器名称，在 Cursor 中用于标识和启用此服务器。
'"command"': 启动服务器的命令，这里使用 'node' 运行 JavaScript 文件。
'"args"': 命令参数，指向编译后的 'server.js' 文件路径。请务必将 '<path-to-your-project>' 替换为您的 'mcp-ynab' 项目的实际本地路径。
'"cwd"': 工作目录，设置为项目根目录。同样需要替换为您的实际项目路径。
'"enabled"': 设置为 'true' 以启用此 MCP 服务器。
'"env"': 环境变量配置。
- '"YNAB_API_TOKEN"': 这是最重要的配置项。您需要将 '"YOUR_YNAB_TOKEN_HERE"' 替换为您在 YNAB 开发者设置中创建的个人访问令牌。 请确保此令牌具有访问您的 YNAB 数据的权限。

配置步骤:

打开 Cursor 的全局配置文件 '~/.cursor/mcp.json' (如果文件不存在则创建)。
将上述 JSON 配置代码添加到 'mcp.json' 文件中的 '"mcpServers"' 字段下。
根据您的实际项目路径和 YNAB API 令牌，修改 '"args"', '"cwd"', 和 '"env.YNAB_API_TOKEN"' 的值。
保存 'mcp.json' 文件。

基本使用方法

确保已按照上述步骤配置并启用了 'mcp-ynab' 服务器。
重启 Cursor 以加载新的 MCP 服务器配置。
在 Cursor 的 MCP 设置中，您应该能看到 'mcp-ynab' 服务器已连接（绿点指示）。
现在，您可以直接在 Cursor 中使用自然语言指令，或明确调用工具来与 YNAB 数据交互。例如：
- 在 Cursor 中提问: "List my YNAB budgets" (列出我的 YNAB 预算)
- 在 Cursor 中提问: "What's the balance of my checking account in my personal budget?" (我的个人预算中，支票账户的余额是多少？)
- 在 Cursor 中提问: "Create a transaction for $20 at Starbucks in my 'Eating Out' category." (在星巴克创建一笔 20 美元的交易，类别为“外出就餐”)

Cursor 的 AI 助手会自动识别并调用 'mcp-ynab' 服务器提供的工具来响应您的请求。您也可以在 Cursor 中手动调用工具，例如使用 'mcp_ynab_list_accounts' 工具并指定 'budget_id' 参数来列出特定预算的账户。

重要提示:

请务必妥善保管您的 YNAB API 令牌，避免泄露。
首次使用前，请仔细阅读 YNAB API 文档和 MCP 协议文档，以充分了解其功能和限制。
根据您的 YNAB 数据量和网络状况，工具的响应时间可能会有所不同。

关键词