YNAB MCP

YNAB MCP

用于将 Claude Code 与 You Need A Budget（YNAB）集成的 YNAB 模型上下文协议（MCP）服务。

概述

此代码库包含一个基于 Docker 的 MCP 服务，可让 Claude Code 与 YNAB（You Need A Budget）账户交互。它实现了 OAuth 流程，并提供全面的 API，用于预算管理、交易跟踪和财务洞察。

已知问题

MCP 工具可用性

目前已发现以下问题：

1. 交易 API——使用 sinceDate 参数时，list_transactions 端点会因“invalid date”错误而失败
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 标准
• 支持只读模式

实现细节

此实现遵循模型上下文协议标准，使用：

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

许可证

MIT

致谢

• YNAB API
• YNAB JavaScript 库
• Anthropic Claude