AI导哈

批量操作金融管理服务器

为YNAB提供的MCP服务器，支持批量操作、确定性分析工具和强大的撤销功能，适用于个人财务管理。

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

使用说明

YNAB MCP服务器

YNAB的MCP服务器，具有批处理操作、确定性分析工具和强大的撤消支持。

[！注意] AI披露： 这个项目是用Claude Code和Cursor构建的。它可以工作并经过测试，但代码在很大程度上是clanker制作的。

亮点

  • 26工具 涵盖预算、账户、交易、类别、目标、计划交易和支出分析
  • 确定性分析 --支出汇总、趋势、收入与支出、经常性费用和异常检测，以及一次性预算健康状况快照。判断调用（预测、重新分配、优先级排序）故意留给调用代理，后者拥有准确的数据和更多的上下文
  • 批量操作 -在一次调用中创建、更新和删除多个事务，在YNAB API没有批量终结点的情况下，记录每个项目的API成本
  • 撤消支持 --每次写入操作都会被记录下来，并且是可逆的
  • 智能分类 --收款人历史记录和计划交易匹配中的交易类别建议，带有置信度门控，因此只有高置信度建议才能进入准备应用的操作
  • 内置知识库 --YNAB方法文件（信用卡、目标、超支、对账）作为MCP资源
  • 5个工作流提示 --月度审查、支出报告、未经批准的分类、预算优化和订阅审计
  • 只读模式 --写工具甚至没有注册，所以客户端只看到他们可以使用的工具
  • 高效缓存 --与YNAB的服务器知识系统、可配置的TTL和客户端速率限制跟踪进行增量同步

设置

先决条件

用法

直接与 npx:

YNAB_API_TOKEN=your-token npx @maro-org/ynab-mcp

或全局安装：

npm install -g @maro-org/ynab-mcp
YNAB_API_TOKEN=your-token ynab-mcp

MCP客户端配置

将服务器添加到MCP客户端配置中。例如，在Claude Desktop中(claude_desktop_config.json):

{
  "mcpServers": {
    "ynab": {
      "command": "npx",
      "args": ["-y", "@maro-org/ynab-mcp"],
      "env": {
        "YNAB_API_TOKEN": "your-token"
      }
    }
  }
}

对于游标，将相同的结构添加到 .cursor/mcp.json 在您的项目或 ~/.cursor/mcp.json 全球地。

配置

所有配置都是通过环境变量完成的。

变量 描述 默认值
YNAB_API_TOKEN YNAB个人访问令牌 必须
YNAB_API_URL 覆盖YNAB API基URL YNAB默认值
YNAB_MCP_DATA_DIR 撤消历史记录存储目录 ~/.ynab-mcp
YNAB_READ_ONLY 隐藏并禁用所有写入操作(true/false/1/0) false
YNAB_CACHE_TTL 以秒为单位缓存实时数据的TTL 3600
YNAB_PAST_MONTH_CACHE_TTL 缓存过去几个月完成的TTL（秒） 86400
YNAB_UNDO_HISTORY_LIMIT 撤消按预算保留的条目（最旧的条目将被删除） 2000

工具

预算

工具 说明
list_budgets 列出所有带有元数据的预算
sync_budget_data 强制刷新YNAB的缓存数据

账户

工具 说明
get_accounts 列出有余额的账户，可按类型和预算内外进行筛选

交易

工具 说明
search_transactions 使用过滤器（日期、金额、账户、类别、收款人、标志、已清除状态）进行搜索——支持一次呼叫中的多个查询
create_transactions 批量创建带有可选拆分的事务（一个批量API调用）
update_transactions 批量更新现有事务（一个批量API调用；通过删除+重新创建替换拆分更改）
delete_transactions 批量删除事务（每个事务一个API调用）

分类

工具 说明
list_categories 带有ID和名称的类别组层次结构
get_targets 目标详细信息：类型、金额、资金不足、完成百分比、节奏和截止日期
get_monthly_budget 每个类别的月度预算/活动/余额
set_category_budgets 批量设置预算金额（每个类别/月对最多两次API调用，最多50次）
set_category_targets 设置或清除类别的目标金额和日期（API不公开目标类型）

支出分析和诊断

工具 说明
get_spending_analysis 按类别/收款人分列的支出总额排名前N位；可选的 time_granularity 桶随着时间的推移而花费
get_spending_trends 按类别、收款人或组划分的多月时间序列；标记当前月份的部分内容，并将其排除在趋势之外
get_income_expense_summary 收入与支出总额及储蓄率；部分当月未计入平均值
get_budget_health 单次通话快照：净值、月总额、超支、目标缺口、信用卡支付缺口、RTA、问题
detect_recurring_charges 从交易历史中检测订阅和经常性费用
detect_anomalies 用遗漏一项的统计基线标记异常交易
get_money_movements 审核类别或准备分配之间的预算变动，包括在YNAB应用程序中进行的变动

所有分析工具都是确定性的，不涉及LLM采样。他们报告事实并明确标注统计估计；预测和重新分配决策留给调用代理（工作流提示使用 get_targets, get_monthly_budget，以及 get_scheduled_transactions).

定期交易

工具 说明
get_scheduled_transactions 使用可选筛选器列出计划交易
create_scheduled_transactions 使用13个YNAB频率中的任何一个进行批量创建（每个项目一个API调用）
update_scheduled_transactions 批量更新计划事务（每个项目一个API调用）
delete_scheduled_transactions 批量删除计划事务（每个项目一个API调用）

智能工具

工具 说明
suggest_transaction_categories 根据收款人历史和模式为未分类交易建议类别

建议具有可信度；只有那些达到或超过 action_confidence （默认值 high)已包含在准备申请中 update_actions，批准为选择加入。

撤销

工具 说明
list_undo_history 列出记录的撤消条目
undo_operations 按ID撤消一个或多个先前的写入操作

资源

YNAB方法的知识库资源。工作流提示会自动引用这些。

URI 主题
ynab://knowledge/terminology YNAB核心概念和术语
ynab://knowledge/credit-cards 信用卡处理
ynab://knowledge/targets 目标类型和行为
ynab://knowledge/overspending 超支的机械师
ynab://knowledge/reconciliation 对账工作流程
ynab://knowledge/api-quirks API的怪癖和局限性

提示词

提示 描述
monthly-review 指导月度预算审查
spending-report 日期范围的支出报告
triage-unapproved 批量审核和批准未批准的交易
budget-optimization 分析预算以寻找优化机会
subscription-audit 审查经常性费用并管理订阅

关键概念

货币单位 --工具输入和输出中的所有货币金额都使用标准货币单位（例如。， 12.50)，而不是YNAB的原生毫单位。大多数工具也与顶级工具相呼应 currency ISO代码； get_spending_analysis 额外报告原始 *_milliunits 他们旁边的总数。

budget_id --大多数工具都接受可选 budget_id.忽略它或通过 "last-used" 针对最近访问的预算。

撤销 --每次写入操作都会记录一个撤消条目。使用 list_undo_history 和 undo_operations 查看或恢复更改。保留每个预算中最近的2000个条目（可通过以下方式进行调整 YNAB_UNDO_HISTORY_LIMIT).

只读模式 --设置 YNAB_READ_ONLY=true 隐藏和阻止所有写入操作。有助于安全地探索您的预算或将MCP客户端限制为只读访问。

速率限制 -YNAB API每滚动小时允许200个请求。服务器在本地跟踪使用情况，并在达到限制时报告容量何时释放。（API用于公开 X-Rate-Limit 跟踪器与标题进行了对账；实时API不再发送它，因此本地跟踪器是唯一的信号，直到429确认耗尽为止。)每个项目花费一个API调用的工具在它们的描述中这样说。

发展

npm install
npm run dev        # run with tsx watch
npm run build      # compile TypeScript
npm test           # run tests (vitest)
npm run typecheck  # type-check without emitting
npm run lint       # lint with Biome
npm run ci         # typecheck + lint + test

许可证

麻省理工学院

相关 MCP