YNAB MCP

YNAB Model Context Protocol (MCP) 服务器用于 Claude Code 与 You Need A Budget (YNAB) 的集成。

概述

此仓库包含一个基于 Docker 的 MCP 服务器，使 Claude Code 能够与 YNAB（您需要预算）账户进行交互。它实现了 OAuth 流程，并提供了一个全面的 API，用于预算管理、交易跟踪和财务洞察。

已知问题

MCP 工具可用性

已发现以下问题：

1. 交易 API - 使用 sinceDate 参数时，list_transactions 端点会因“无效日期”错误而失败
2. 缺少 API 工具 - 源代码中定义的一些端点在 MCP 集成中不可用
3. 行为不一致 - 在使用 test-mcp.js 进行测试时某些工具可以正常工作，但在实际 MCP 集成中却失败了

问题追踪

我们正在积极解决以下问题：

• fix-transactions-api 分支：处理交易 API 中的日期格式问题
• fix-mcp-registration 分支：确保所有 API 工具都正确注册并可用

功能

• 基于 OAuth 的 YNAB API 认证
• 完整的预算和账户管理
• 交易创建和分类
• 先进的类别管理，包括批量分配和建议
• 支持多个预算（个人和家庭）
• 处理速率限制（YNAB API 限制：每小时 200 次请求）
• 缓存以提高性能

新类别管理功能

此 MCP 包含先进的类别管理功能：

• 分配到类别：将资金从“准备分配”一次性分配到多个类别
• 推荐分配：根据目标和消费模式获得基于 AI 的预算分配建议

详情请参阅 类别管理文档。

快速开始

先决条件

• Docker
• Node.js v18+（开发用途）
• Claude Code CLI
• YNAB 账户

安装

1. 克隆此仓库
2. 将 config/config.example.js 复制到 config/config.js 并添加您的 YNAB API 凭据
3. 构建 Docker 镜像：docker build -t ynab-mcp:latest .
4. 为 Claude 创建 JSON 配置：

   {
     "command": "docker",
     "args": [
       "run",
       "--rm",
       "-i",
       "-v",
       "/path/to/data:/app/data",
       "-v",
       "/path/to/config:/app/config",
       "-e",
       "NODE_ENV=production",
       "ynab-mcp:latest"
     ]
   }
   

5. 使用 Claude Code CLI 注册 MCP：

   claude mcp add-json ynab '{"command": "docker", "args": ["run", "--rm", "-i", "-v", "/path/to/data:/app/data", "-v", "/path/to/config:/app/config", "-e", "NODE_ENV=.production", "ynab-mcp:latest"]}'
   

   您也可以将 JSON 保存到文件中并使用：

   claude mcp add-json ynab "$(cat config.json)"
   

6. 当 Claude 提示时，使用您的 YNAB 账户进行认证

与 Claude 的集成

此 MCP 可无缝集成到 Claude 中，允许：

• 查看预算和交易
• 获取财务洞察
• 通过自然对话管理预算

安全

• 令牌安全存储在挂载的 Docker 卷中
• 不记录敏感数据
• 认证使用 OAuth 2.0 标准
• 支持只读模式

实现细节

实现遵循 Model Context Protocol 标准，使用：

• Node.js 和官方 MCP SDK
• Docker 进行容器化和部署
• YNAB JavaScript SDK 进行 API 操作
• OAuth 2.0 进行认证

许可证

MIT

致谢

• YNAB API
• YNAB JavaScript 库
• Anthropic Claude