ynab-mcp-server

ynab-mcp-server

一个用于与你在 https://ynab.com 上的 YNAB 计划交互的模型上下文协议（MCP）服务

要让 AI 与此工具交互，你需要从 YNAB 获取个人访问令牌：https://api.ynab.com/#personal-access-tokens。将此 MCP 服务添加到任何客户端时，你需要将个人访问令牌作为 YNAB_API_TOKEN 提供。**此令牌绝不会直接发送给大模型。**它会私密地存储在环境变量中，供 YNAB API 使用。

一个模型上下文协议服务，可让 AI 助手读取和修改 YNAB 计划。

该服务通过官方的 ynab SDK 与 YNAB API 通信。你的个人访问令牌存储在环境变量中，绝不会发送给模型。

它可以通过同一代码库以两种方式运行：

• 本地（stdio） — 在你自己的设备上，作为 Claude Code 或 Claude Desktop 的子进程运行。最简单，但只在该设备开机且服务运行时可用。
• 远程（Cloudflare Worker） — 部署在 GitHub 登录保护之后，并作为自定义连接器添加到 claude.ai，这样即使你的电脑关机，也能在网页和移动应用中使用。请参阅 DEPLOY.md。

两个入口点都会注册 src/registry.ts 中的共享工具。Worker 还可以运行可选的定时自动预算服务，记录它将如何分类、批准和分配资金，但不会更改你的计划，并发送支出提醒；请参阅自动预算服务。

其他提供方：

设置

从 https://api.ynab.com/#personal-access-tokens 获取个人访问令牌，然后：

npm install
npm run build

环境变量：

变量	必需	用途
YNAB_API_TOKEN	是	用于每次 API 调用的个人访问令牌
YNAB_PLAN_ID	否	默认计划，这样工具就可以省略 planId。使用 ynab_list_plans 查找。
TYPESAFE_API_KEY	否	由操作者持有的 TypeSafe 凭据。启用类别建议的必要条件，但仅凭此项还不够。
YNAB_AI_CATEGORIZATION	否	与 TYPESAFE_API_KEY 一起设置为 "true"，以启用可选的建议工具。
YNAB_AI_TYPICAL_PAYEES	否	设置为 "true"，即可在每次模型请求中发送各类别过去 12 个月最常见的收款方名称。默认关闭，因为这会向 TypeSafe 披露汇总后的收款方历史记录。
YNAB_READ_ONLY	否	设置为 "true"（不区分大小写；会忽略首尾空格），以移除会写入 YNAB 的工具，包括 stdio 服务和 Worker 中的工具。

本地：Claude Desktop / Claude Code

{
  "mcpServers": {
    "ynab": {
      "command": "node",
      "args": ["/absolute/path/to/ynab-mcp-server/dist/index.js"],
      "env": {
        "YNAB_API_TOKEN": "your-token",
        "YNAB_PLAN_ID": "your-plan-id"
      }
    }
  }
}

远程服务：手机和 claude.ai

上面的 stdio 服务无法从手机访问。要在 claude.ai 或 Claude 移动应用中使用这些工具，请将 src/worker/ 部署到 Cloudflare Workers，并将其添加为自定义连接器。DEPLOY.md 提供了完整的操作指南；大致步骤如下：

1. 将 wrangler.example.jsonc 复制为被 git 忽略的 wrangler.jsonc；除非你要配置自动预算服务，否则删除可选的占位 AUTOBUDGET_DB 块；运行 npx wrangler login，然后创建 OAUTH_KV 命名空间
2. 运行一次 npm run deploy，以获取你的 *.workers.dev 主机名
3. 创建一个 GitHub OAuth 应用，其回调地址为 https://<host>/callback
4. 使用 npx wrangler secret put 设置 ALLOWED_GITHUB_LOGIN、YNAB_API_TOKEN、GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET 和 TYPESAFE_API_KEY
5. 再次运行 npm run deploy
6. 在 claude.ai 中将 https://<host>/mcp 添加为自定义连接器

YNAB 令牌会一直作为 Worker 密钥保存，不会传到客户端。GitHub 登录用于控制谁可以连接远程 Worker；YNAB 个人访问令牌用于控制可以访问哪个 YNAB 账户。两者解决的是不同问题，不能互相替代。Worker 使用一个全服务通用的 YNAB 令牌，因此，通过 GitHub 验证的任何人都能访问部署者的 YNAB 账户、资金，以及该令牌可访问的所有预算，而不是他们自己的 YNAB 账户。 ynab_list_plans 会列出所有这些预算；调用方提供的 planId 会覆盖可选的 YNAB_PLAN_ID 默认值。除 ALLOWED_GITHUB_LOGIN 之外的任何 GitHub 账户都会被拒绝。由于这组工具可以创建和删除交易，这一点很重要——未验证身份的端点会让任何找到 URL 的人都能访问这些预算。

Worker 并非只能与 Claude 搭配使用。任何支持通过 OAuth 连接远程服务的 MCP 客户端都可以连接，例如 Claude（claude.ai、桌面版和移动版）、ChatGPT 连接器、Claude Code 或 MCP Inspector。由于客户端会自行注册，每次获准的登录都会显示一个审批页面，其中列出客户端名称，以及授权将发送到的确切地址；只批准你刚刚发起的登录。若要限制可连接的客户端，将 ALLOWED_REDIRECT_URIS 设置为它们的确切回调 URI（本地客户端的环回重定向仍允许使用）。回调 URI 示例请参见审批 MCP 客户端。

为什么不支持 YNAB OAuth？

我们有意不支持 YNAB OAuth。即使使用 PKCE，其令牌交换仍需要客户端密钥；开源软件包无法随附密钥，因此本地软件包无法如实实现授权码流程（OAuth 应用要求）。 YNAB 文档中唯一无需密钥的流程是隐式授权，有效期为两小时且无法刷新（OAuth 应用要求）。 YNAB 建议个人使用个人访问令牌访问自己的账户（个人访问令牌）。

将 YNAB_READ_ONLY 设为 "true" 会从工具列表中移除所有 YNAB 写入工具；如果你主要在手机上使用连接器，值得考虑这样设置。

工具

针对预算的工具接受可选的 planId，未提供时会回退到 YNAB_PLAN_ID。可选工具输入可以为 null；服务会将 null 视为未提供该输入。所有金额——无论流入还是流出——都使用普通货币金额，而非 YNAB 的毫单位。报告金额使用预算币种的精度（例如科威特第纳尔等币种保留三位小数）；如果无法读取其设置，则回退到两位小数。转换逻辑位于 src/tools/money.ts。

查看数据

工具	功能
ynab_list_plans	账户中的所有计划。首先运行此工具以查找计划 ID。
ynab_plan_summary	一目了然地查看某个月的数据：收入、预算金额、活动金额、待分配金额，以及分为 overspent、underfunded（尚未达成目标）和 positive_balance 的类别。隐藏和已删除的类别不会显示。budgetVsActuals: true 会添加一个 budget_vs_actuals 区块，其中包含每个类别的 budgeted、activity、balance、variance（预算金额加活动金额）和 percent_used（未分配任何金额时为 null），并按类别组和在 totals 中分别汇总。信用卡付款会作为单独的类别组列出，但不计入 totals，因为其活动金额是信用卡支出减去还款。YNAB 内部的 Inflow: Ready to Assign 类别（其活动金额即为当月收入）会被跳过；其他内部类别（例如 Uncategorized）若有活动金额，则会列出并计入统计。
ynab_list_accounts	显示账户及其余额。设置 includeClosedAccounts 可查看已关闭的账户。
ynab_list_categories	按类别组分组显示类别，并附带目标信息。
ynab_list_payees	显示收款方，用于查找收款方 ID。
ynab_list_months	显示计划开始以来的所有月份，并包含原始收入、预算金额、活动金额、待分配金额、资金存续时间和备注字段。若要查看近期收入与支出，请使用 ynab_cash_flow。
ynab_list_scheduled_transactions	显示在 YNAB 中设置的计划交易。若要查看交易历史中发现的定期费用，请使用 ynab_detect_recurring；若要查看预测余额，请使用 ynab_balance_forecast。
ynab_get_transactions	可选按 sinceDate–untilDate、按 type（all/uncategorized/unapproved），以及按 accountId、categoryId 或 payeeId 中至多一个筛选交易（按此顺序优先匹配）。若要搜索，可添加 payeeContains、memoContains（不区分大小写）、minAmount/maxAmount（忽略正负号）或 direction（outflow/inflow/any）；任何搜索选项或 untilDate 都会添加一个 totals 区块（count、inflow、outflow、net），统计所有匹配项，包括账户间转账；设置 totalsOnly: true 则只返回该区块。若未提供 categoryId 或 payeeId，则逐笔匹配拆分交易，且总计只统计匹配的部分；若提供了其中任一项，则按 YNAB 返回的行进行匹配，因此收款方列表中拆分交易的父行会按全额计入。limit 默认为 100，且不会影响总计。
ynab_suggest_categories	为未经批准、未分类的普通流出交易提供可选的只读类别预览。默认模式下会剔除已删除和已分类的行；符合相应条件的已批准、已对账、余额调整、转账、拆分和流入行会被跳过。

类别建议（可选）

ynab_apply_category_suggestions 是一个独立的写入工具，无需启用 TypeSafe 预览即可使用。最多可提供 25 行明确的 transaction_id、category_id 和 expected_content_fingerprint。该 工具会重新获取每笔交易，并拒绝已过时或不符合条件的更改；若重试时该类别已应用，则不执行任何操作。它支持仅验证的试运行，并返回写入前的撤销清单，但不会执行撤销。它绝不会自动应用建议、调用 TypeSafe 或批准交易。

ynab_suggest_categories 默认处于关闭状态。若要启用该工具，请设置由运维人员管理的 TYPESAFE_API_KEY 和 YNAB_AI_CATEGORIZATION=true，然后重启 服务。API 密钥从环境变量（或 Worker 密钥）中读取，绝不会从工具参数中读取。省略 transactionIds、传入 null 或传入空 数组时，工具会获取未经批准的交易，并仅保留未分类的行；提供 ID 则只检查这些交易。在默认模式下，工具会对每一条保留的行检查其是否符合确定性条件，然后按 YNAB 返回的顺序，将 limit 应用于最先出现的符合条件的流出交易。被跳过的行不会占用上限。 该工具用于预览，不会写入 YNAB、批准交易，也不会改变 ynab_update_transaction 的行为。它会先在代码中处理确切事实——移除已删除的行，并处理已批准或已对账的行、YNAB 余额调整、转账、拆分、流入、已有类别以及隐藏／内部类别。在默认模式下，transactions 仅包含已检查的符合条件的行，transaction_count 为这些行的数量，eligible_transaction_count 则报告应用限制前所有符合条件的行数。顶层 skipped 对象会报告 total_count，并为每种原因提供 count 和 transaction_ids：skipped_approved、skipped_reconciled、skipped_balance_adjustment、skipped_transfer、skipped_split、skipped_inflow 和 skipped_already_categorized。显式指定 transactionIds 时，每条已获取的非删除行都会作为单独结果保留，包括状态为 skipped_* 的行；已删除的行则会被省略。收款方历史记录使用最近 12 个月的数据，最多包含 50 条符合条件的行。如果该收款方没有符合条件且收款方 ID 相同的行，历史记录会回退到名称相似的收款方：经过 Unicode NFC 规范化、转为小写并移除除字母和数字以外的所有字符后，一个名称以另一个名称开头，且较短名称至少有 6 个字符，因此，截断后的银行收款方名称（例如 “Better Bl”）会使用 “Better Blend” 的历史记录。每个历史记录摘要都会报告 match（payee、similar_payee_name 或 null）和 matched_payee_names。

随后，每条符合条件的行都会按以下顺序处理，source 会指出给出答案的步骤：

1. 精确收款方历史记录（history_rule）。 如果至少有一条符合条件的行具有相同的收款方 ID，且所有此类行都使用同一个仍符合条件的类别，则该类别为 suggested。如果这些行的类别不一致，则该行状态为 needs_review，并提出最近使用的类别，其余类别则作为 top_alternatives，并附带各自的 history_count。这两种情况都不会调用模型。
2. 个人先验（personal_prior）。 每次请求都会训练一个朴素贝叶斯分类器，使用计划中最近 12 个月历史记录里的已分类普通支出，并以收款方名称和银行导入名称的词元、账户以及粗略金额区间作为特征。当历史记录中包含至少两个类别的已分类行时，会使用该分类器；单一类别的先验无法对备选类别排序。训练中从未出现过的名称词元会被忽略，而不会参与评分。当最高类别的概率达到 0.9 时，该行会标为 suggested，且不会调用模型。该概率会显示在 personal_prior.ranking 下，而不会显示为 model_confidence。低于 0.9 时，先验仅用于排序：前三个类别会显示在模型处理的行中，供比较。
3. 模型（jev）。 所有剩余行都会分批提交给 TypeSafe 固定版本的 jev-1.13.0 System One 模型，每批 10 条。模型答案是排序后的候选列表，不是建议：凡是答案中包含类别，状态均为 needs_review；若模型明确弃答，则状态为 left_uncategorized。因此，该固定模型存储的审核阈值为 0；由于不同模型的置信度尺度各不相同，阈值会按模型区分。 相似名称历史记录从来不是规则；当某一行交由模型处理时，它只会作为提示性证据纳入考量。历史摘要中的 reference_category_id 是用于比较提案的类别：对于精确收款方历史记录，使用最近一次采用的类别；对于相似名称历史记录，使用出现次数最多的类别。相似名称不一致会报告为 conflict，但不会改变状态，因为前缀匹配无法确认商家身份。每条经过检查且符合条件的记录都包含状态、来源、内容指纹、提议类别、模型置信度和获胜概率（仅限模型处理的记录）、最多三个备选项、历史摘要，以及计算出的个人先验排序。响应中的 thresholds 对象会报告当前生效的阈值，personal_prior 则会报告用于训练先验的记录数，以及该先验是否可用于路由。应用建议仍然是单独且明确的人为决策，使用 ynab_apply_category_suggestions（或通用的 ynab_update_transaction 工具）执行。

为何采用这种顺序：不同家庭对收款方的归类方式各不相同，例如将餐馆归入杂货类别，或将诊所归入储蓄类别。通用模型无法了解这些习惯，但计划自身的历史记录可以体现出来。在真实家庭历史记录上，历史规则和个人先验的准确度远高于对相同记录使用模型的准确度。模型给出的高置信度答案出错的频率远高于合成测试样例中的情况，因此它们仅供审核。若要评估自己的计划或本地模型，请参阅评估分类和本地决策模型。

启用此功能会将交易的显示收款方、导入时的／原始收款方、备注、金额、日期和账户名称／类型／是否计入预算，以及可见的类别组和类别名称发送给 TypeSafe 作为第三方处理商。对于有相似名称匹配且需要交由模型处理的记录，还会发送匹配的收款方名称，以及每个类别的键、组、名称和计数。当 YNAB_AI_TYPICAL_PAYEES=true 时，每次模型请求还会列出过去 12 个月内每个类别中最常见的最多八个收款方名称（typical_payees），并在响应中设置 typical_payees_sent: true。这能显著提高模型对某个家庭自身归类习惯的判断准确度，但也会披露汇总后的收款方历史记录，因此默认关闭。它不会发送 YNAB UUID、余额、目标、审批／已清算状态或原始交易历史记录。由历史记录或个人先验处理的记录绝不会被发送。截至本次发布时，TypeSafe 公布的 Jev 1.13 价格为每百万输入令牌 $0.042；输出令牌免费。每次运行时，工具都会返回预检估算、实际令牌用量和预计费用，并拒绝超出单次调用令牌数／费用上限的请求。价格和提供商限制可能会变动；请查看 https://docs.typesafe.ai/models。

此原型刻意限定了适用范围，且默认未启用。其最初的 98.3% 精确标签准确率、98.9% 前三项准确率和 60/60 预期弃答结果，来自 40 个由单人评估的合成测试样例，并非生产环境准确率声明。正如上文所述，真实家庭历史记录要复杂得多。

报告

在支出报告中，拆分交易会通过其子交易计入，而您自有账户之间的转账会被排除，因此报告反映的是支出，而非资金流动。

工具	功能
ynab_spending_by_category	按类别统计日期范围内的总支出，按金额从高到低排列，并显示占总额的比例。默认统计最近 30 天。启用 monthly: true 后，每个类别还会显示各日历月的支出、完整月份的平均值，以及最近一个完整月份相较于更早完整月份的变化；统计范围为最近 months 个月（默认 6，最多 24 个月），或从 sinceDate 开始；sinceDate 会覆盖 months，此时 untilDate 默认设为今天。总额为支出总额，不会扣除退款。
ynab_spending_by_payee	同上，按商家分组，包含 monthly。
ynab_cash_flow	按月统计收入与支出以及累计净额，使用 YNAB 自身的月度总额。默认统计最近 6 个月。
ynab_balance_forecast	根据仅包含计划交易的预测，计算未来 days 天（默认 30 天，最多 365 天，从 UTC 的今天起）账户的合计余额：起始余额、计划事件、每日结束时的滚动余额、最低点和期末余额。accountIds 用于选择账户；默认包括所有开放的预算内账户。limit 用于限制事件数量（默认 100，设为 0 则不返回事件）；event_count、滚动余额、最低点和期末余额始终涵盖所有事件。两个入选账户之间的转账（包括信用卡还款）净额为零；转入预测范围外账户的转账计为资金流出，从此类账户转入的转账则计为资金流入。如果 YNAB 尚未录入已过日期的发生项，则将其计入第一天，并标记为 overdue，同时在 overdue_schedules 中汇总并提供其 scheduled_date。对于每月两次的计划，如果 YNAB 未提供第二个日期，则将其近似设为第一个日期之后 15 天，并标记为 approximate。
ynab_detect_recurring	检测订阅和账单等定期支出：找出金额相近、按固定间隔（每周至每年）向同一收款方支付的费用，并提供典型金额、按最近金额计算的年度费用、下次预计日期、是否似乎已停止，以及是否存在收款方名称相同的计划交易。贷款和抵押贷款还款属于转账，因此不会纳入；退款也不会抵扣。此功能基于启发式规则，默认统计最近 365 天。

写入

工具	功能
ynab_create_transaction	创建交易。需要提供 date、amount、账户（accountId 或 accountName）和收款方（payeeId 或 payeeName）；类别可选，可通过 categoryId 或 categoryName 指定，也可使用 subtransactions 拆分交易。
ynab_update_transaction	更新现有交易的任意字段子集，也可通过 subtransactions 将未拆分的交易拆分。
ynab_delete_transaction	删除交易。无法撤销。
ynab_bulk_approve_transactions	在一次 API 调用中批准一组交易 ID，或通过 approved: false 取消批准。
ynab_apply_category_suggestions	应用最多 25 条明确的类别建议，支持重新获取数据、过时数据检查、试运行，以及写入前的撤销清单。绝不会自动应用类别建议或批准交易。
ynab_update_category_budget	设置某个月单个类别的预算总额。此操作不是增量调整；如需在类别之间转移资金，请使用 ynab_move_money。
ynab_import_transactions	从已关联的金融机构导入交易，效果与在 YNAB 应用中点击 Import 相同。
ynab_move_money	在某个月的两个类别之间转移预算资金，用于弥补超支。
ynab_auto_assign	将 Ready to Assign 中的资金分配到尚未达到月度目标的类别，优先填补缺口最大的类别。使用 dryRun 预览，使用 maxTotal 设置上限。

使用名称而非 ID

ynab_create_transaction 接受 accountName 和 categoryName，并与预算计划中的名称进行宽松匹配，因此“ally checking”可以匹配 Ally Checking。 已关闭的账户和隐藏的类别永远不会被匹配。如果名称有歧义或无法识别，调用会失败，并列出相近的匹配项，而不会自行猜测；成功调用会返回 matchedAccount / matchedCategory，以便发现错误匹配。

拆分交易

ynab_create_transaction 和 ynab_update_transaction 可在提供 subtransactions 时将一笔交易拆分到多个类别：需要提供两个或更多 { amount, category_name, payee_name, memo } 条目，其格式与 ynab_get_transactions 为拆分交易返回的格式相同。金额以美元计，且总和必须与交易金额完全相等（更新时，如果提供了新的 amount，则与之相等；否则与当前金额相等）；类别应设置在拆分项上，而非父交易上。拆分项的类别名称会像 categoryName 一样进行匹配，并通过 matchedSplitCategories 返回。

YNAB 无法更改已拆分交易的拆分项，因此 ynab_update_transaction 会拒绝此类操作，而不是悄悄丢弃更改。要重新拆分，请删除并重新创建该交易。

可能部分成功的写入操作

YNAB 没有在类别之间转移资金的端点，因此 ynab_move_money 会通过两次调用重写两个类别的预算金额。它会先从来源类别扣款，因此如果中途失败，资金会留在“Ready to Assign”中，而不会被重复计算。发生这种情况时，响应会设置 partial: true，并附带一条 recovery 信息，其中包含需要恢复的原始金额。ynab_auto_assign 的行为类似：失败时会报告哪些类别已获得资金，以及哪些类别未发生变化。

工具绝不会在协议层面抛出异常。失败会以 MCP 错误结果返回（isError: true），并在文本内容中包含 { "success": false, "error": "..." }，因此不会将失败的写入操作误认为成功。

工具注释

每个工具都会在其架构旁声明 MCP 注释（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）。不会更改 YNAB 或 Worker 服务状态的工具，其 readOnlyHint 为 true；在 YNAB 写入工具中，只有 ynab_delete_transaction 的 destructiveHint 为 true。客户端可以使用这些提示来判断哪些调用需要确认提示。

cleared 和 flagColor

ynab_create_transaction 和 ynab_update_transaction 接受 cleared，其值可以是 cleared、uncleared 或 reconciled；也接受 flagColor，其值可以是 red、orange、yellow、green、blue、purple 或 ""（用于清除现有标记）。

开发

npm run watch          # rebuild on change
npm test               # vitest (watch mode)
npm run test:run       # vitest, single run
npm run test:coverage  # coverage report
npm run typecheck      # typecheck both the node and Worker targets
npm run debug          # build, then open the MCP inspector
npm run dev:worker     # run the Worker locally with wrangler
npm run deploy         # deploy the Worker to Cloudflare

dist/ 是构建产物，不会纳入 git 跟踪；运行 npm run build 可重新生成它。

发布

更新 package.json 中的版本并更新 CHANGELOG.md，然后合并到 main，并按照现有的 0.2.0 风格创建 GitHub 发布标签（不带 v 前缀）。工作流会通过 npm 暂存该发布，但不会公开软件包。维护者必须运行 npm stage list 并审核，然后通过 2FA 运行 npm stage approve，将其正式发布。请在 npmjs.com 上为 ynab-mcp-server 配置 Trusted Publisher，指向 GitHub 仓库 calebl/ynab-mcp-server 和确切的工作流文件名 .github/workflows/publish.yml（文件名必须完全匹配）；在 Allowed actions 下仅选择 npm stage publish。

添加工具

每个工具都是 src/tools/ 中的独立模块，导出 name、 description、inputSchema（Zod 形状）和 execute(input, api)。请参阅 CLAUDE.md 中的完整模板，然后将该模块添加到 src/registry.ts 的 tools 数组中，并在 src/tests/ 中编写测试。在此处注册后，该工具便会同时由 stdio 服务和 Worker 提供；如果工具会更改数据，请标记 writes: true，因为 YNAB_READ_ONLY 会根据此标记进行筛选。

有用的参考资料：

• YNAB SDK 类型：node_modules/ynab/dist/index.d.ts
• YNAB OpenAPI 规范：https://api.ynab.com/papi/open_api_spec.yaml

贡献

欢迎提交拉取请求。对于新工具或较大的更改，请先提交 issue，以便我们就范围达成一致。

1. Fork 仓库，并从 main 创建分支。
2. 进行更改，并在 src/tests/ 中添加或更新测试。新工具请遵循添加工具中的模式。
3. 运行 npm run test:run 和 npm run typecheck。
4. 提交信息和拉取请求标题请使用约定式提交。
5. 向 main 提交拉取请求。

每个拉取请求都会在 Node.js 22、24 和 26 上运行测试套件，并接受自动化代码审查。两项检查都必须通过，且审查讨论必须全部解决，拉取请求才能合并。

兼容性

budgetId 和 YNAB_BUDGET_ID 已弃用，但仍可使用；目前没有移除日期。新集成请使用 planId 和 YNAB_PLAN_ID。

许可证

请参阅 LICENSE。