AI导哈

预算API协议服务

一个为YNAB（You Need A Budget）API提供的模型上下文协议服务器，允许MCP客户端读取预算、账户和交易信息，并通过结构化工具创建或重新分类交易。

  • by klauern
  • Python
  • 本地部署
  • 6 星标
  • 更新于
在 GitHub 查看 klauern/mcp-ynab

使用说明

mcp-ynab

A. 模型上下文协议 服务器 你需要一个预算 （您需要预算）API。允许MCP客户端（Claude 桌面、Claude Code、定制代理）读取您的预算、账户和 交易，并通过结构化工具创建或重新分类交易。

安装

该项目由以下人员管理 紫外线 和 任务。此仓库中的所有Python命令都经过 uv run.

uv sync                  # install dependencies
task install             # install the mcp-ynab CLI into the venv

配置

在环境中（或在 .env 文件在 回购根）：

export YNAB_API_KEY=your-personal-access-token

获取令牌 https://app.ynab.com/settings/developer.

快速启动

1.设置API密钥

代码模式是默认的表面-它需要您的YNAB API键：

export YNAB_API_KEY="your-key-here"

或者将其存储在您的操作系统密钥链中（服务器会自动读取）。

2.使用代码模式

默认情况下，服务器公开两个工具： search （发现可用操作）以及 execute （针对实时YNAB API运行一个代码段）。

发现工具：

# In the search tool:
return [t for t in spec if "transaction" in t["name"]]

执行查询：

# In the execute tool:
return await ynab.read.get_budgets()

3.恢复整个刀具表面（可选）

要访问所有约34个直接YNAB工具，请设置逃生口首选项：

set_preference: code_mode_replace_tools = false

运行服务器

mcp-ynab                 # production
task dev                 # dev mode + MCP Inspector in the browser

工具与资源

默认情况下，公共MCP工具界面故意较小：

工具 目的
search 在没有实时API访问的情况下发现可用的YNAB操作
execute 针对实时YNAB API运行一个简短的Python代码段
ping 对服务器进行健康检查
get_preferences 检查服务器首选项
set_preference 更新首选项，如突变或逃逸图案填充设置
set_api_key 将YNAB API密钥存储在操作系统密钥链中
clear_api_key 删除存储的YNAB API密钥
set_preferred_budget_id 缓存默认目标呼叫的首选预算ID

使用 search 发现操作：

return [
    {"name": tool["name"], "description": tool["description"]}
    for tool in spec
    if "category" in tool["name"]
]

然后通过调用操作 execute:

categories = await ynab.read.get_categories()
return [
    {"name": category.name, "balance": category.balance}
    for group in categories
    for category in group.categories[:LIMIT]
]

突变操作在下面进行 ynab.write.* 并要求 code_mode_mutations_enabled=true:

result = await ynab.write.bulk_categorize(assignments=assignments)
return result

底层直接工具仍然存在于内部FastMCP注册表中，因此 代码模式可以通过以下方式进行调度 ynab.read.*，生成存根，并构建 搜索目录。默认情况下，它们在公共工具列表中隐藏。集 code_mode_replace_tools=false 将整个直接刀具表面恢复为 逃生舱。

代表性的内部直接工具包括：

只读内部工具

工具 目的
get_budgets 以低价列出所有预算
get_accounts 列出预算中的科目，按类型分组并汇总
get_account_balance 返回单个账户的当前美元余额
get_transactions 账户最近的交易；可选的 since_date
get_transactions_needing_attention 未分类/未批准交易的筛选器
get_categories 按类别组分组的预算中的所有类别

更改内部工具

工具 目的
create_transaction 在YNAB中创建新交易
categorize_transaction 为现有交易分配类别
set_preferred_budget_id 缓存默认目标工具的首选预算ID
cache_categories 在本地缓存预算的类别列表

对于账户转账和信用卡支付，请使用目标账户的 转账收款人ID为 payee_id 创建或更新事务时。这 get_payees 工具列出转账收款人及其 Transfer Account ID. 不要通过a Transfer : ... 值为 payee_name；YNAB拒绝或治疗 作为常规收款人，而不是创建链接转账。

资源

  • ynab://preferences/budget_id --当前首选预算ID
  • ynab://categories/{budget_id} --预算的缓存类别
  • ynab://code-mode/stubs --为代码模式生成Python存根
  • ynab://code-mode/examples --精心策划的代码模式片段

代码模式

代码模式公开 execute，一个用于多步骤YNAB的Python执行工具 工作流程。默认情况下，它处于启用状态，并通过首选项进行控制 code_mode_enabled, code_mode_mutations_enabled，以及 code_mode_replace_tools.

看 src/mcp_ynab/code_mode/README.md 有关使用方法、接线说明和转轮限制。

发展

task fmt                 # ruff format + check --fix
task lint                # ruff check + format --check (no auto-fix)
task typecheck           # mypy
task docstrings          # interrogate (fails under 80%)
task test                # unit tests only (default; integration excluded)
task coverage            # unit tests with coverage report

集成测试

集成测试在后面进行 pytest.mark.integration 并被排除在外 默认 task test 跑。他们会给你的YNAB账户打电话，所以他们 需要 YNAB_API_KEY.

YNAB_API_KEY=your-token task test:integration

默认集成套件为 只读.变异数据的测试 （create_transaction，categorye_transaction）需要额外的选择加入：

YNAB_API_KEY=your-token YNAB_INTEGRATION_ALLOW_WRITES=1 \
  task test:integration

许可证

麻省理工学院

相关 MCP