mcp-for-ynab

YNAB 的 MCP

面向 YNAB 的快速、安全 MCP 服务——为 Claude 和其他 AI 助手提供完整预算访问权限，默认只读。

35 个工具，涵盖预算、交易、类别、收款方、账户、预定交易，以及由服务端计算的分析数据（支出摘要、预算健康状况、周期性收费、收入与支出、净资产、月末覆盖情况、类别和信用卡垫付历史）。默认关闭写入，只有在你明确启用后才会开放；高风险写入需要确认，编辑或删除现有数据的写入操作可以撤销。

安装

运行 Cove for YNAB 有两种方式：本地（npm 包，一次运行一个客户端）或远程（一个 URL 加令牌，可在桌面、Code 和移动端使用，体验一致）。

安装（本地）

通过 npx 在你的设备上运行。支持 Claude Code 和 Claude Desktop。移动端无法访问——移动客户端需要使用下方的远程方式。

Claude Code：

claude mcp add ynab -e YNAB_ACCESS_TOKEN=xxx -- npx -y @walensis/cove-mcp

Claude Desktop——将以下内容添加到配置文件（claude_desktop_config.json）中：

{
  "mcpServers": {
    "cove": {
      "command": "npx",
      "args": ["-y", "@walensis/cove-mcp"],
      "env": {
        "YNAB_ACCESS_TOKEN": "xxx"
      }
    }
  }
}

将 xxx 替换为你的个人访问令牌（参见下方的获取令牌）。服务默认只读；想要使用写入工具时，可在 env 中添加 "YNAB_ALLOW_WRITES": "1"（或在 Claude Code 的 -e 中导出该变量）——参见默认只读（写入需主动启用）。

任何通过 stdio 使用 MCP 的其他客户端，也可以用同样的方式运行服务：

npx -y @walensis/cove-mcp

并在其环境中设置 YNAB_ACCESS_TOKEN。

安装（远程）

只需一个 URL 和令牌，即可在 Claude Desktop、Claude Code 和移动端的 claude.ai 上获得一致的使用体验——无需保持本地进程运行。这是 apps/worker，一个单租户 Cloudflare Worker，你可以部署到自己的账户并使用自己的 YNAB 令牌：apps/worker/README.md 提供了完整的部署指南，以及如何配置各类客户端连接到它。

**简而言之，其模式是：**此仓库中的所有内容——引擎、stdio 服务和远程端点——都是开源且免费的，并且属于工具：无状态、按需响应、自身不会主动执行任何操作。任何自主运行或按量计费的功能——始终开启的垫付监控、摘要、大模型撰写的叙述、浏览器扩展——都属于产品，位于我们运营并收费的独立托管服务中。自托管此 Worker 可永久免费使用工具部分；但不包含始终开启的部分。如果你更愿意基于同一个开源引擎自行构建这些功能，请参见 docs/build-your-own-monitoring.md。

获取令牌

1. 前往 app.ynab.com 并登录。
2. 打开账户设置 → 开发者设置。
3. 在个人访问令牌下，点击新建令牌，确认密码，然后复制令牌。
4. 将该值用作 YNAB_ACCESS_TOKEN。请像对待密码一样妥善保管——任何拥有该令牌的人，只要令牌有效，就能完整访问你的预算。

如果你不想将令牌直接放入 MCP 客户端配置中，可以将 YNAB_ACCESS_TOKEN_FILE 设置为仅包含令牌的文件路径。

默认只读，写入需主动启用

默认情况下，此服务仅提供读取工具——它执行的任何操作都不会改变你的预算。如需启用写入工具（创建／编辑／删除交易、分配资金等），请在服务的环境中设置：

YNAB_ALLOW_WRITES=1

然后重启服务。启用写入后：

• 确认门槛：破坏性操作或批量操作（删除交易、删除计划交易、批量更新超过 5 笔交易）需要显式设置 confirm: true——批量更新还需要将 expected_count 设为与行数一致——这样助手就必须先向你展示即将执行的操作，再进行操作。
• 撤销：会更改现有数据的写入操作——编辑／删除交易、编辑类别、分配／转移预算、编辑／删除计划交易、重命名收款方——会记录在本地日志中，undo_last 工具会撤销最近一次操作（最多保存 50 条写入历史，存储在 ~/.cove/undo.json 中）。创建内容的写入操作（create_category、create_payee、create_account）以及 import_transactions 无法撤销——YNAB 的 API 不支持删除类别、收款方或账户，也无法撤销导入操作。这些操作仍会记入日志（以保持撤销历史顺序），但如果 undo_last 遇到无法撤销的条目，会告知你并继续处理之前的写入操作。有关该文件的详情，请参阅 PRIVACY.md。

速率限制

底层 API 每个令牌每小时允许 200 次请求，所有使用同一令牌的应用共享此限额（此服务、YNAB 的移动应用和 Web 应用、其他集成等）。此服务会在客户端跟踪自身用量，并在每小时达到 190 次请求时停止，以便为你的其他应用留出余量；此外，在可行的情况下，它优先返回较小的服务端计算结果（聚合数据、摘要），而不是倾倒原始行数据。

工具

工具	类型	描述
list_plans	读取	列出所有预算（计划）：ID、名称、货币、最后修改时间。
get_plan_overview	读取	一次调用即可了解概况：账户、当月 Ready to Assign、资金存留时间、类别总额。
get_month	读取	查看某个月的完整详情：Ready to Assign、资金存留时间、每个类别的状态。
list_transactions	读取	按筛选条件、分页和字段选择列出或汇总交易。
get_transaction	读取	查看一笔交易的完整详情，包括拆分后的子交易。
create_transactions	写入	批量创建一笔或多笔交易，支持拆分和导入去重。
update_transactions	写入	批量编辑交易：分类、批准、设置结清状态、编辑字段。
delete_transaction	写入	删除一笔交易。需要确认。
import_transactions	写入	触发导入关联账户的交易。
list_scheduled_transactions	读取	列出所有计划交易（即将发生／定期交易）。
create_scheduled_transaction	写入	创建计划交易（即将到期的账单或定期收入）。
update_scheduled_transaction	写入	更新计划交易。
delete_scheduled_transaction	写入	删除计划交易。需要确认。
list_categories	读取	列出所有可见类别及其余额和目标状态。
create_category	写入	创建类别（如有需要，也会创建其分组）。
update_category	写入	重命名或隐藏类别，或设置其目标。
assign_budget	写入	设置某个月某个类别的分配金额。
move_money	写入	在某个月的两个类别之间转移已分配资金，操作具有原子性。
list_payees	读取	列出所有收款方（ID、名称、转账标记）。
rename_payee	写入	重命名某个收款方在其所有交易中的名称。
create_payee	写入	创建收款方。
create_account	写入	创建账户并设置初始余额。
spending_summary	读取	由服务端计算按类别或收款方汇总的支出，可选进行期间对比。
budget_health	读取	检查当月预算状况：超支、目标资金不足、信用卡浮动额。
detect_recurring_charges	读取	根据约 13 个月的历史记录查找定期费用（订阅／账单）。
income_vs_expense	读取	按月列出收入／支出／净额序列。
net_worth_history	读取	根据完整交易历史计算按月列出的净资产序列。
month_close	读取	截止日期的月结报告：信用卡覆盖情况、阻碍项、超支类别、按优先级排序的资金提供类别。
propose_coverage	读取	按顺序提出资金转移方案，以便将截止月份的所有超支类别余额归零。
get_category_history	读取	查看某个类别在指定月份范围内的月度序列（已分配／活动／可用）。
credit_card_float_history	读取	查看指定范围内每月的信用卡浮动额分析：欠款与还款类别可用金额、差额、变更标记。
backfill_ledger	本地写入	根据历史记录回填本地余额结转账本：每张卡在每个已完整结束的月份记一条记录，附带原因和发现摘要（“自 起结转 $X”）。仅操作本地文件（~/.cove/ledger.json）——绝不触及 YNAB。
record_month_close	本地写入	持久化月结余额结转记录（每张卡的差额、阻碍项、原因、已应用的资金转移）。仅操作本地文件（~/.cove/ledger.json）——绝不触及 YNAB。
get_month_close_ledger	读取	读取过去的余额结转记录（最新记录优先），可按截止日期筛选。
undo_last	写入	撤销通过此服务执行的最近一次写入。

月末结账会话

基于上述工具构建的月度引导式梳理流程（余额 → 计划）：它会逐一处理阻碍项，直到确认覆盖缺口可信；将信用卡浮动余额的变化归因于其原因；提出优先使用捐赠方预算项的覆盖调整；在你批准后，通过 record_month_close 写入结转余额记录，让下个月的会话可以通过 get_month_close_ledger 与之对照。首次运行时，账本为空——会话会先为每张卡运行 backfill_ledger，并首先展示发现的情况（例如“自 2024-08 起结转 $865.75”），再进一步进行归因。

• Claude Code：使用 /month-close 技能。
• Claude Desktop 和其他 MCP 客户端：服务将同一流程作为 month-close-session MCP 提示词公开。
• 完整操作指南：docs/playbooks/month-close.md。

远程 MCP 端点（自托管）

远程工作器（参见上文的安装（远程））通过经过令牌身份验证的远程 MCP 端点提供相同的 35 个工具——包括供支持请求头的客户端使用的 bearer 请求头路由，以及令牌位于路径中的路由，使 claude.ai 仅支持 URL 的自定义连接器也能直接访问你的预算。该端点基于此软件包为嵌入式使用导出的同一库入口构建：

import { tools, buildServer } from '@walensis/cove-mcp'

它不包含持续运行的监控功能——那是单独托管的产品。如果你想基于同一开放归因引擎自行构建监控功能，请参阅 docs/build-your-own-monitoring.md。

完整部署指南：apps/worker/README.md。

开发

这是一个 pnpm monorepo：packages/core（@walensis/cove-core，用于 YNAB 的 API 客户端和领域逻辑）以及 apps/mcp（@walensis/cove-mcp，对其进行封装的 MCP 服务）。

命名： Cove 是产品；@walensis/cove-core 是引擎，@walensis/cove-mcp 是 MCP 接口，而 MCP 注册表条目保留了便于发现的描述性名称 mcp-for-ynab。

pnpm install
pnpm build
pnpm test
pnpm typecheck

针对真实预算进行冒烟测试（只读——绝不会写入）：

YNAB_ACCESS_TOKEN=xxx pnpm smoke

使用已知正确的样例值验证 credit_card_float_history（只读）：

YNAB_ACCESS_TOKEN=xxx pnpm validate:fixtures

免责声明

我们与 YNAB 或其任何子公司、关联公司均无隶属、关联关系，也不存在任何官方联系。

许可证

MIT © walensis-labs