MCP Server for YNAB

YNAB MCP 服务

向你的预算提问。 将 Claude、Codex、Cursor 或任何 MCP 客户端连接到 YNAB，获取关于你实际资金状况的解答——本月进展如何、哪些类别超支，以及订阅的真实费用。

YNAB_API_KEY=your_token uvx mcp-server-for-ynab smoke

默认只读。 除非设置 YNAB_ALLOW_WRITES=1，否则不会注册写入工具，因此助手看不到这些工具；在你明确启用之前，预算不会发生任何变化。启用后，每次写入都会记录操作前的状态，并且可以撤销。

这是一个 MCP 服务，将 YNAB API 封装为工具，并提供增强型工具，回答原始 API 无法通过一次调用回答的问题——预算健康状况、清理队列、支出分析和定期扣款。

快速开始

1. 获取 YNAB 令牌

在 app.ynab.com/settings/developer 生成个人访问令牌。

你还需要 uv，它提供 uvx：

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS and Linux
brew install uv                                   # macOS with Homebrew
winget install --id=astral-sh.uv -e               # Windows

确认两者都能正常工作。无需克隆任何内容——uvx 会获取程序包并在临时环境中运行：

YNAB_API_KEY=your_token uvx mcp-server-for-ynab smoke

smoke 会验证配置和工具注册，然后退出。它应输出 smoke: app created, 62 tools registered。

2. 将其添加到客户端

客户端	设置方式
Claude Code	一条命令
Claude Desktop	配置文件
Cursor	一键链接
VS Code（GitHub Copilot）	一条命令
Codex CLI	一条命令
Gemini CLI	一条命令
Windsurf、Zed 等	通用 stdio 配置
MCP Inspector	调试

最常见的两种方式：

Claude Code — 安装插件，它会自带 MCP 配置：

/plugin marketplace add hs737/mcp-server-for-ynab
/plugin install mcp-server-for-ynab@mcp-server-for-ynab

如果不想使用插件，也可以直接注册服务：

claude mcp add --env YNAB_API_KEY=your_ynab_token --transport stdio --scope user \
  ynab -- uvx mcp-server-for-ynab stdio

Claude Desktop、Cursor、Windsurf 和大多数其他客户端 — 将以下内容粘贴到客户端的 MCP 配置文件中：

{
  "mcpServers": {
    "ynab": {
      "command": "uvx",
      "args": ["mcp-server-for-ynab", "stdio"],
      "env": {
        "YNAB_API_KEY": "your_ynab_token",
        "YNAB_PLAN_ID": "your_plan_id"
      }
    }
  }
}

YNAB_PLAN_ID 是可选项，但建议设置 — 设置后，你就不必在请求中指定预算名称。各客户端的完整说明（包括配置文件的位置，以及如何避免将令牌保存在配置文件中）请参阅 客户端设置。

支持安装包的桌面宿主 — 从 最新版本 下载 .mcpb 文件并打开。宿主会通过表单询问你的令牌，并将其存储在操作系统的密钥链中，因此无需编辑配置文件，也不会将令牌以纯文本形式保存。 你可以通过复选框控制是否启用写入。

Docker

已发布的镜像支持 linux/amd64 和 linux/arm64。该服务通过 stdin 和 stdout 使用 MCP，因此请使用 -i 附加运行。无需发布端口：

docker run -i --rm -e YNAB_API_KEY=your_ynab_token \
  ghcr.io/hs737/mcp-server-for-ynab

或者从克隆的仓库自行构建：

docker build -t mcp-server-for-ynab .
docker run -i --rm -e YNAB_API_KEY=your_ynab_token mcp-server-for-ynab

如果启用了写入，请挂载一个卷来保存历史记录 — 否则 --rm 会丢弃用于恢复操作的记录：

docker run -i --rm -e YNAB_API_KEY=your_ynab_token -e YNAB_ALLOW_WRITES=1 \
  -v ynab-mcp-history:/home/app/.mcp-server-for-ynab mcp-server-for-ynab

3. 问它一个问题

我所有账户的现金状况如何？

如果能正常工作，就说明已准备就绪。如果不行，请参阅 故障排除 — 通常是因为客户端无法在其 PATH 中找到 uvx。

你可以询问什么

开箱即用的只读功能：

询问	调用的工具
“本月预算情况如何？”	overview_month_health
“我所有账户的现金状况如何？”	overview_cash_position
“哪些交易还需要分类？”	triage_uncategorized
“有哪些事项正等着我审批？”	triage_unapproved
“哪些分类超支了，超了多少？”	analysis_overspent_categories
“本月哪些目标无法获得资金？”	analysis_target_funding_gaps
“有哪些计划交易可能存在风险？”	analysis_upcoming_scheduled_risks
“过去一年我在这个收款方那里花了多少钱？”	bookkeeping_transaction_history
“我实际上在为哪些订阅付费？”	analysis_recurring_charges
“这个账户与对账单匹配吗？有哪些问题？”	reconcile_preview
“这是银行 CSV——双方分别缺少哪些记录？”	transactions_match_statement
“我的账户里有没有一直未入账的银行卡预授权？”	triage_pending_imports

启用 YNAB_ALLOW_WRITES=1 后：

将上周尚未分类的交易分类，然后告诉我你做了哪些更改。

Agent 会对交易进行分类，而 history_list 会显示每项写入操作及其操作前的值。history_revert 可以撤销其中任何一项。

Agent 最好先调用 overview_available_tools，获取按类别分组的当前工具目录。完整列表请参阅工具概览。

引导式工作流

服务随附七个提示词，大多数客户端会将它们显示为斜杠命令——无需先阅读工具列表即可开始：月度回顾、每周分类处理、分类并审批、订阅审计、现金状况、回顾并撤销，以及多月预算审计。

四项资源（ynab://guide/*）介绍 YNAB 方法、写入安全规则、工具选择指南以及信用账户的运作方式。这些资源按需获取，因此客户端不请求时不会产生任何开销。

配置

变量	必填	描述
YNAB_API_KEY	是	YNAB 个人访问令牌
YNAB_PLAN_ID	建议	默认计划 ID，让大多数工具无需填写 plan_id
YNAB_ALLOW_WRITES	否	注册写入工具。未设置时为只读
YNAB_HISTORY_PATH	否	写入历史文件，默认为 ~/.mcp-server-for-ynab/history.jsonl
YNAB_RATE_LIMIT_PER_HOUR	否	客户端每小时请求额度，默认为 YNAB 200 次额度中的 190 次
YNAB_RATE_WARN_THRESHOLD	否	剩余请求数达到此值时发出警告，默认为 50
LOG_LEVEL	否	日志详细程度，默认为 INFO

在 MCP 客户端的 env 块中设置这些变量。本地开发时，将 .env.example 复制为 .env 并填写内容。

速率限制

YNAB 每个令牌每小时允许 200 次请求，而单个增强型工具可能会消耗多次请求。服务会在滚动的一小时内跟踪自身用量，并在达到 YNAB 上限前停止，因此触发的限制是本地限制，并会明确报告，而不是在工作流进行到一半时收到 429 错误。

每个工具响应都包含 requests_used_this_hour 和 requests_remaining，类似 HTTP API 返回 X-RateLimit-Remaining——Agent 可以根据已显示的数字自行控制请求节奏，无需额外调用来查询额度，否则那次查询本身也会消耗一次不会发出的请求。overview_request_budget 会提供限制、时间窗口以及额度耗尽后何时恢复；ping 则会检查服务是否正在运行。这两项都不消耗请求额度。

配额归访问令牌所有，因此你自己的 YNAB 应用也会消耗该配额。这里显示的是本服务已使用的请求数，可能低于 YNAB 剩余的额度——每次速率限制错误都会说明这一点，并同时提供额度恢复的绝对时间戳和等待时长，确保计划的重试不会过早发起。

工具系列

62 个只读工具、84 个启用写入的工具，另有 7 个引导式提示词和 4 个参考资源。

系列	类型	用途
overview	enriched	预算健康状况概览与方向指引
triage	enriched	交易清理队列
bookkeeping	enriched	分类建议、备注辅助和历史记录
analysis	enriched	超支、资金缺口、预定风险、信用卡资金和跨月审计
reconcile	enriched	对账单比对、银行导出数据匹配和完成对账
history	enriched	查看并回滚此服务执行的写入
changes	enriched	查看自指定 server_knowledge 值以来的变动
user	raw	YNAB 用户信息
plans	raw	预算计划和设置读取
accounts	raw	账户读取和创建
categories	raw	分类和分类组
months	raw	月度预算数据、跨月范围和批量分配
payees	raw	收款方管理
payee_locations	raw	收款方地理元数据，使用范围较窄／优先级较低
transactions	raw	交易的 CRUD 操作和导入触发
scheduled_transactions	raw	预定交易管理
money_movements	raw	资金流动数据，以及在分类之间转移资金

原始工具与 YNAB 端点非常接近——用于精确读取和大多数写入操作。增强工具将多次读取合并为一个答复——用于了解情况、调查和分析。每个工具都标记为 read 或 write；除非工具名称和说明明确表明会写入，否则增强工具不会执行写入。

阅读大量预算数据，而不是大量 JSON

真实预算计划的单个月份数据约为 60 KB 的 JSON，因为 YNAB 会返回每个分类的所有目标字段，包括隐藏分类。以这种方式检查一整年数据无法放入上下文窗口。

• months_get 和 categories_list 接受 compact=true，每个分类只返回六个字段，而非三十个——数据量约为原来的四分之一。
• months_range 将整个时间范围作为一个按分类和月份排列的矩阵返回，因此检查二十一个月只需一次调用，而非二十一次。
• category_groups_summary_by_month 在分类组级别执行相同操作，而大多数“情况是否健康”类问题实际上都涉及这一层级。
• changes_since 会报告自某个 server_knowledge 值以来的变动，因此用户编辑预算后，只需进行一次小型调用即可重新检查。

范围工具仍会为每个月消耗一次 YNAB 请求——因为 YNAB 没有范围端点——因此每个工具都会说明其开销，且范围上限为 36 个月。

更多详情：工具接口

写入工具

除非主动启用，否则不会注册写入工具：

YNAB_ALLOW_WRITES=1

未启用时，服务为只读状态，写入工具也不会出现在 tools/list 中——Agent 看不到的工具自然无法调用。这是有意为之：此服务持有的凭据可以修改真实财务记录，而在执行时拒绝调用仍会暴露此项能力。

每次写入都会记录，大多数都可以撤销

启用写入后，每次写入都会记录写入前的状态。 YNAB 没有历史记录端点，因此这是恢复被覆盖值的唯一方式。

工具	用途
history_list	最近的写入，按时间从新到旧排列，并标记每项是否可撤销
history_show	完整显示一条记录，包括写入前的状态
history_revert	撤销一次写入
history_revert_to	将计划回滚到指定记录时的状态

history_revert_to 会按从新到旧的顺序撤销指定记录之后的所有操作，因为对同一记录的重叠编辑只有按相反顺序撤销才能正确还原。撤销操作本身也会被记录，因此撤销操作也可以撤销。

无法撤销的操作。 YNAB 没有删除账户、类别、类别组或收款人的路由，因此创建这些项目后便无法删除。这些操作会被记录为不可撤销，并说明原因；回滚时会将它们列在 blocked 下，而不是悄悄跳过——声称成功却未完成的回滚，不如明确告知遗留内容。重新创建的交易也会获得新的 ID，并失去与银行导入记录的关联。

写入会经过验证，而不是想当然

更改值的工具会在写入后重新读取该值，并返回一个 verification 区块。收到 200 响应并不能证明写入成功：YNAB 接受类别更新路由中的 budgeted，返回 200，却忽略该值。验证机制可以发现这一点。

应用计划与转移资金

YNAB 的 API 按月份逐个类别分配资金，因此一个月的计划需要 35 次单独写入，并产生 35 条单独的历史记录。

• months_assign_many 会在一次调用中应用整个月的计划，并将其记录为一条历史记录，因此可以作为一个整体决策撤销。
• money_move 会在两个类别之间转移可用资金，也可以转入或转出 Ready to Assign；它会读取当前金额并进行计算，因此不会把结转余额误认为已分配金额。
• reconcile_apply 会完成对账：通过一次批量调用将已确认的交易标记为已对账，并发布用于结清剩余差额的调整，将两者作为一条记录写入，以便一并撤销。

这两个分配工具也支持使用 adjust_by 而非总额——例如“向此类别增加 $4,500”，无需先读取当前数值，因为工具无论如何都会读取该值，以记录撤销时应恢复的金额。这并非原子增量：YNAB 的 API 不支持增量操作或条件写入，因此工具会先读取金额，再写入合计；在这两次调用之间，如果有人在应用中编辑了金额，该编辑就会被覆盖。传入 expected_budgeted 后，如果读取到的金额与预期不符，写入就会被拒绝；因此，调用方依据的数值若已发生变化，操作会停止，而不会覆盖该值。这只是写入前的检查，并非写入的前置条件：读取与写入之间的间隙仍然存在，因为 YNAB 的路由没有提供任何方法来消除这个间隙。 无论使用哪种方式，响应都会报告 previous_budgeted、budgeted 和 change，因此无需重新读取也能确认写入结果。

这些操作都不是原子的，因为 YNAB 没有事务边界。每项操作都会报告已应用和失败的内容；即使 money_move 只完成了部分写入，也仍会记录在历史中，以便将资金转回。

通过 Agent 执行对账前，有一点值得了解：YNAB 的 API 没有设置账户 last_reconciled_at 的路由。交易确实会被标记为已对账，但应用仍会显示上次在应用中完成对账的日期；工具会明确说明这一点，而不会将账户报告为已对账。

金额约定

所有 YNAB 货币金额均以毫单位表示：1000 = $1.00。

• 原始工具对规范金额字段接受并返回毫单位。
• 增强型工具可能会在规范值旁提供便于显示的辅助值。

你的数据

此服务只会在你的机器上存储一项内容：它所执行写入操作的记录，供 history_revert 使用。除 api.ynab.com 外，不会向任何地方发送数据，也没有遥测。

uvx mcp-server-for-ynab history --show          # where it is, how much is there
uvx mcp-server-for-ynab history --export out.json
uvx mcp-server-for-ynab history --delete        # also removes the ability to revert

这些操作无需凭据，也无需 Agent：取回数据或删除数据，都不应该需要运行大模型。

贡献者须知

此仓库的结构旨在让贡献者或 AI Agent 能快速回答三个问题：MCP 服务位于何处、YNAB API 封装和模型位于何处，以及在哪里添加新工具、测试和文档。

flowchart LR
    A["MCP Client"] --> B["MCPServer Server"]
    B --> C["Tool Handlers"]
    C --> D["ynab_client"]
    D --> E["http_client (httpx)"]
    E --> F["YNAB API"]
    C --> G["enriched/"]
    G --> D

代码围绕少量几层组织：

• src/mcp_server_for_ynab/server/：MCPServer 应用、工具元数据、工具注册、错误边界
• src/mcp_server_for_ynab/ynab_client/：每个 YNAB 资源系列对应一个异步封装模块
• src/mcp_server_for_ynab/http_client/：用于对外请求的 httpx 封装，包含重试、脱敏和错误规范化
• src/mcp_server_for_ynab/models/：类型化的 YNAB 数据结构、共享错误模型、毫单位辅助工具
• src/mcp_server_for_ynab/enriched/：基于原始客户端构建的更高层只读工作流
• tests/：单元、契约、集成和 QA/Postman 源文件

从克隆的仓库运行：

git clone https://github.com/hs737/mcp-server-for-ynab
cd mcp-server-for-ynab
uv sync
cp .env.example .env    # then set YNAB_API_KEY

make smoke-stdio
make run-stdio
make run-http

运行测试：

make test
make test-unit
make test-contract
make test-integration
make test-postman-operator

这些测试会检查服务是否正常工作。evals/ 要回答的是另一个问题——助手是否正确地使用它。该项目真正遇到的问题都出在这里：循环操作本应只调用一次，却导致速率限制锁定；某个账户被报告为已对账，但 YNAB 仍显示其状态过时。这些案例由模型评分，而非通过断言验证，因此需要时可使用 claude plugin eval 运行，而不会在 make check 中运行。参见 evals/README.md。

接下来阅读哪些内容

如果你正在：

• 连接客户端：客户端设置
• 初次接触此仓库：架构
• 添加代码：贡献指南、仓库结构、Agent 指南
• 添加或修改工具：工具范围、Agent 评测
• 验证行为：测试
• 处理身份验证、错误处理或日志记录：安全
• 发布版本或添加渠道：分发 — 发布说明就是标签注释，因此请在打标签前撰写

完整索引：文档索引。另请参阅：Postman 说明、 法律声明。

当前状态

当前实现使用 Python 3.12、官方 mcp 包中的 MCPServer、贯穿全程的 asyncio、用于向外发起 YNAB 调用的 httpx，以及内置的 stdio 和 streamable HTTP 传输方式。

这是一个本地个人访问令牌服务。尚未实现托管或公开连接器——其中包括 ChatGPT 自定义连接器，因为它们需要远程 HTTPS 端点，而非本地进程。我们的设想是让托管运行时位于自己的仓库中，通过其嵌入接口导入此包，从而将 OAuth 和公开应用相关问题排除在此项目之外。

如果架构与实现有任何不一致，应以架构为准，并更新它以反映实际代码。

许可证

Apache License 2.0。请参阅 LICENSE 和 NOTICE.md。

免责声明

我们与 YNAB 或其任何子公司、关联公司均无关联、关系或任何官方联系。YNAB 官方网站地址为 https://www.ynab.com。

YNAB 和 You Need A Budget 这些名称，以及相关名称、商号、标志、商标、徽章和图像，均为 YNAB 的注册商标。