ynab-mcp

Name: ynab-mcp
Author: EdgeCaseLabs

作者：EdgeCaseLabs2 星标更新：2025-10-15

安装使用来源：spider==github.com

项目介绍

YNAB MCP Server

一个提供全面访问YNAB（https://www.ynab.com）即“你需要预算”API的模型上下文协议（MCP）服务器。此服务器将所有YNAB API功能暴露为MCP工具，允许AI助手和其他MCP客户端与YNAB预算、账户、交易等进行交互。

功能

完整的YNAB API覆盖：所有YNAB API方法都作为MCP工具暴露
uv集成：快速依赖管理
类型安全：使用Python类型提示和Pydantic模型构建
错误处理：全面的错误处理和日志记录
调试日志：可选的工具调用日志记录用于调试MCP交互
环境配置：通过环境变量进行简单配置
组织化的工具结构：工具按类别逻辑分组（预算、账户、交易等）

预备条件

安装了Python 3.10+ 和 uv
拥有一个带有个人访问令牌的YNAB账户

获取您的YNAB API密钥

登录到您的YNAB账户 https://app.ynab.com
导航至账户设置
前往开发者设置部分
创建一个新的个人访问令牌
安全保存此令牌——您将在配置中需要它

安装

快速安装（推荐）

如果您已安装uv，可以直接运行服务器而不需克隆：

# 如果尚未安装，请安装uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 直接从PyPI运行服务器
uvx ynab-mcp-server

# 或启用调试日志
uvx ynab-mcp-server --logging

从PyPI安装

# 使用pip
pip install ynab-mcp-server

# 或使用uv
uv pip install ynab-mcp-server

# 运行服务器
ynab-mcp-server

从源码安装

克隆仓库：

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

安装依赖：

uv sync

复制并配置环境：

cp .env.sample .env
# 编辑.env文件，添加您的YNAB API密钥

测试服务器：

# 正常运行
uv run python -m ynab_m
# 启用调试日志运行
uv run python -m ynab_m --logging

配置

环境变量

变量	必要	描述	默认值
`YNAB_API_KEY`	是	您的YNAB个人访问令牌	-
`DEFAULT_BUDGET_ID`	否	当未指定时使用的默认预算ID	`last-used`
`LOG_LEVEL`	否	日志级别（DEBUG, INFO, WARNING, ERROR）	`INFO`
`MCP_SERVER_NAME`	否	MCP服务器名称	`YNAB MCP Server`

可用工具

用户工具

get_user() - 获取认证用户信息
verify_api_key() - 验证API密钥有效性

预算工具

get_budgets(include_accounts) - 获取预算列表
get_budget_by_id(budget_id, last_knowledge_of_server) - 获取详细的预算信息
get_budget_settings(budget_id) - 获取预算设置

账户工具

get_accounts(budget_id, last_knowledge_of_server, include_closed, include_deleted) - 获取账户（默认排除关闭/删除的）
get_account_by_id(account_id, budget_id) - 获取特定账户
create_account(name, type, balance, budget_id) - 创建新账户
get_account_balance(account_id, budget_id) - 获取账户余额

交易工具

get_transactions(budget_id, since_date, type, last_knowledge_of_server) - 获取交易
get_transaction_by_id(transaction_id, budget_id) - 获取特定交易
create_transaction(...) - 创建新交易
update_transaction(...) - 更新现有交易
delete_transaction(transaction_id, budget_id) - 删除交易
import_transactions(budget_id) - 从关联账户导入交易

分类工具

get_categories(budget_id, last_knowledge_of_server) - 获取所有分类
get_category_by_id(category_id, budget_id) - 获取特定分类
get_month_category(category_id, month, budget_id) - 获取特定月份的分类
update_category(category_id, name, note, hidden, budget_id) - 更新分类
update_month_category(category_id, month, budgeted, budget_id) - 更新月度预算
get_category_balance(category_id, month, budget_id) - 获取分类余额

收款人工具

get_payees(budget_id, last_knowledge_of_server) - 获取所有收款人
get_payee_by_id(payee_id, budget_id) - 获取特定收款人
update_payee(payee_id, name, budget_id) - 更新收款人名称
search_payees(search_term, budget_id) - 按名称搜索收款人
get_payee_locations(budget_id) - 获取所有收款人位置
get_payee_location_by_id(payee_location_id, budget_id) - 获取特定位置
get_payee_locations_by_payee(payee_id, budget_id) - 获取收款人的位置

使用示例

Claude Desktop配置

要将此YNAB MCP服务器连接到Claude Desktop，您需要在Claude Desktop设置中进行配置。

配置Claude Desktop

创建或编辑您的Claude Desktop配置文件：

macOS/Linux: ~/.config/claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

添加YNAB MCP服务器配置（参见claude_desktop_config.json以获取完整示例）：

{
  "mcpServers": {
    "ynab": {
      "command": "uvx",
      "args": ["ynab-mcp-server"],
      "env": {
        "YNAB_API_KEY": "your_ynab_api_key_here",
        "DEFAULT_BUDGET_ID": "optional_default_budget_id"
      }
    }
  }
}

替代配置：

如果从源码安装：

{
  "mcpServers": {
    "ynab": {
      "command": "/path/to/uv",
      "args": ["run", "--directory", "/absolute/path/to/ynab-mcp", "python", "-m", "ynab_mcp_server"],
      "env": {
        "YNAB_API_KEY": "your_ynab_api_key_here",
        "DEFAULT_BUDGET_ID": "optional_default_budget_id"
      }
    }
  }
}

要启用调试日志，在args数组中添加"--logging"：

"args": ["ynab-mcp-server", "--logging"]

重要：

将/path/to/uv替换为您系统上which uv的输出
将/absolute/path/to/ynab-mcp替换为项目目录的实际绝对路径

重启Claude Desktop

更新配置后，重启Claude Desktop。您现在应该可以在对话中看到YNAB工具。

测试连接

尝试让Claude帮助您处理预算：

"显示我当前的预算"
"我的支票账户余额是多少？"
"创建一笔25美元的咖啡交易在星巴克"
"这个月我在杂货上花了多少钱？"

与其他MCP客户端一起使用

一旦服务器运行，您可以使用任何兼容MCP的客户端连接到它。这里是一些示例工具调用：

# 获取所有预算
result = await client.call_tool("get_budgets", {"include_accounts": True})

# 获取本月的交易
result = await client.call_tool("get_transactions", {
    "budget_id": "default",
    "since_date": "2024-01-01"
})

# 创建一笔新的交易
result = await client.call_tool("create_transaction", {
    "account_id": "account-uuid",
    "amount": -25000,  # 25.00美元以毫单位计
    "date": "2024-01-15",
    "payee_name": "Coffee Shop",
    "category_id": "category-uuid",
    "memo": "早晨咖啡",
    "cleared": "cleared"
})

# 更新当前月份的分类预算
result = await client.call_tool("update_month_category", {
    "category_id": "category-uuid",
    "month": "2024-01-01",
    "budgeted": 500000  # 500.00美元以毫单位计
})

理解毫单位

YNAB使用毫单位表示所有货币值：

1美元 = 1000毫单位
10.50美元 = 10500毫单位
-25.00美元 = -25000毫单位（负数表示支出）

开发

运行测试

uv run pytest

代码检查和格式化

# 格式化代码
uv run black ynab_mcp_server/

# 检查代码
uv run ruff ynab_mcp_server/

# 类型检查
uv run mypy ynab_mcp_server/

添加新工具

要添加新工具，创建或修改ynab_mcp_server/tools/中的文件，并在ynab_mcp_server/server.py中注册它们：

创建带有MCP装饰器的工具函数
添加详尽的文档字符串
合适地处理错误
在主服务器中注册

架构

ynab-mcp/
├── ynab_mcp_server/        # 主包
│   ├── __init__.py         # 包初始化
│   ├── __main__.py         # 模块入口点
│   ├── server.py           # 主MCP服务器
│   ├── debug_utils.py      # 调试日志实用工具
│   └── tools/              # 工具实现
│       ├── budgets.py      # 预算相关工具
│       ├── accounts.py     # 账户工具
│       ├── transactions.py # 交易工具
│       ├── categories.py   # 分类工具
│       ├── payees.py       # 收款人工具
│       └── user.py         # 用户工具
├── pyproject.toml          # uv依赖
├── uv.lock                 # 锁定依赖
├── claude_desktop_config.json # 示例Claude Desktop配置
├── CLAUDE.md               # Claude Code开发指南
└── .env.sample            # 环境模板

调试

调试日志

服务器支持调试日志以帮助排查MCP工具调用问题：

# 启用调试日志（如果从PyPI安装）
ynab-mcp-server --logging

# 或使用uvx
uvx ynab-mcp-server --logging

# 或从源码
uv run python -m ynab_mcp_server --logging

启用后，所有工具调用将以stderr格式记录：

TOOL_CALL: function_name(param1='value', param2=42)

这特别有用当：

调试Claude Desktop集成问题
理解哪些工具被调用及其参数
排查意外的工具行为

故障排除

API密钥问题

确保您的API密钥正确设置在.env文件中
使用verify_api_key工具验证密钥
检查密钥是否在您的YNAB设置中过期

连接问题

检查网络连接
确保可以访问YNAB API
验证Claude Desktop能否找到uv命令（使用完整路径）

速率限制

YNAB API有速率限制。此服务器适当处理速率限制响应，但请注意：

每小时最多200次请求
速率限制每小时重置
考虑缓存频繁访问的数据

安全性

切勿提交包含真实API密钥的.env文件
将API密钥安全存储在环境变量中
定期轮换API密钥
尽可能使用只读密钥

贡献

欢迎贡献！请：

分叉仓库
创建功能分支
为新功能添加测试
确保所有测试通过
提交拉取请求

许可

MIT许可 - 查看LICENSE文件了解详情

支持

对于问题和疑问：

查阅YNAB API文档
查阅MCP文档
在GitHub上打开问题

致谢

使用官方YNAB Python SDK构建
由Model Context Protocol驱动
使用uv进行快速依赖管理