ynab-mcp
ynab-mcp
一个公开完整 YNAB API 的 MCP (Model Context Protocol) 服务器,允许 LLM 通过自然语言读取和管理您的预算。提供用于 CRUD 操作的工具、用于环境预算上下文的资源,以及用于引导财务工作流的提示词。
要求
Node.js 20+
一个 YNAB 个人访问令牌
Related MCP server: YNAB MCP Server
安装
npm install -g ynab-mcp或从源码安装:
git clone https://github.com/justmytwospence/ynab-mcp.git
cd ynab-mcp
npm install
npm run build
npm install -g .配置
将您的 YNAB API 令牌设置为环境变量:
export YNAB_API_TOKEN="your-token-here"在 YNAB > 账户设置 > 开发者设置 中生成令牌。
Claude Code
claude mcp add ynab-mcp ynab-mcp -e YNAB_API_TOKEN=your-token-hereClaude Desktop
添加到您的 claude_desktop_config.json:
{
"mcpServers": {
"ynab-mcp": {
"command": "ynab-mcp",
"env": {
"YNAB_API_TOKEN": "your-token-here"
}
}
}
}工具
50 个涵盖完整 YNAB API 的工具。所有金额均使用 YNAB 的毫单位格式(例如 $12.34 = 12340)。
速率限制感知
YNAB API 对每个令牌的限制为 每小时 200 次请求(滑动窗口)。服务器会跟踪每次调用并公开:
get_api_usage工具 /ynab://api-usage资源 — 显式、按需检查(0 次 API 调用)。自动警告:一旦使用量变高,每个工具结果后都会附加警告:
[RATE LIMIT WARNING]:剩余 50 次或更少时[RATE LIMIT CRITICAL]:剩余 20 次或更少时[RATE LIMIT REACHED]:剩余 0 次时
每个工具的描述中都包含其 API 调用成本(例如 [1 API call])。请优先使用批量工具(create_transactions,update_transactions)而不是单次调用工具的循环。
用户
工具 | 描述 |
| 获取已认证用户信息 |
预算
工具 | 描述 |
| 列出所有预算及可选的账户信息 |
| 获取预算的完整详情,包括所有实体 |
| 获取日期和货币格式设置 |
账户
工具 | 描述 |
| 列出所有账户及其余额和类型 |
| 获取单个账户的详情 |
| 创建新账户 |
类别
工具 | 描述 |
| 列出所有按类别组分组的类别 |
| 获取单个类别的详情 |
| 创建新类别 |
| 更新类别的名称、备注或目标 |
| 获取特定月份的类别预算 |
| 更新某个月份中类别的预算金额 |
| 创建新的类别组 |
| 更新类别组名称 |
交易
工具 | 描述 |
| 列出交易(带可选过滤器) |
| 获取单个交易的详情 |
| 创建新交易 |
| 批量创建多个交易 |
| 更新现有交易 |
| 批量更新多个交易 |
| 删除交易 |
| 从关联的金融机构导入 |
| 列出特定账户的交易 |
| 列出特定类别的交易 |
| 列出特定收款人的交易 |
| 列出特定月份的交易 |
计划交易
工具 | 描述 |
| 列出所有计划/定期交易 |
| 获取计划交易的详情 |
| 创建新的计划交易 |
| 更新计划交易 |
| 删除计划交易 |
收款人
工具 | 描述 |
| 列出所有收款人 |
| 获取单个收款人的详情 |
| 更新收款人名称 |
收款人位置
工具 | 描述 |
| 列出所有收款人 GPS 位置 |
| 获取单个收款人位置 |
| 获取特定收款人的所有位置 |
月份
工具 | 描述 |
| 列出所有预算月份及摘要 |
| 获取包含类别余额的详细月份信息 |
资金变动
工具 | 描述 |
| 列出所有资金变动 |
| 获取特定月份的资金变动 |
| 列出所有资金变动组 |
| 获取特定月份的资金变动组 |
工作流
工具 | 描述 |
| 将源类别合并到目标类别,移动所有交易和预算金额 |
| 清理待删除类别:将所有历史记录重新分类到替代类别并将预算归零(最终删除需在 YNAB 应用中手动完成 — API 限制) |
| 审计信用卡付款类别余额与卡余额是否一致,支持可选的自动修复 |
资源
资源提供结构化的预算数据,客户端无需调用工具即可将其引入上下文。模板资源使用 URI 参数(例如 {budget_id})。
资源 | URI | 描述 | API 成本 |
API 使用情况 |
| 当前速率限制状态:已用调用次数、剩余次数、窗口重置时间 | 0 |
预算摘要 |
| 包含账户、余额和类别组的预算概览 | 1 |
账户列表 |
| 所有账户及其类型、余额、已清算/未清算余额 | 1 |
月度类别 |
| 某个月份的所有类别及其预算、活动和余额 | 1 |
提示词
提示词是引导式工作流模板,用户可以调用它们来完成常见的预算任务。它们会指示 LLM 调用哪些工具以及如何解读结果。
提示词 | 参数 | 描述 |
|
| 审查预算月份:超支类别、支出差异、未达标目标、信用卡不匹配 |
|
| 审计交易:查找未分类、未批准、重复及金额异常的交易 |
|
| 引导式演练:账户、类别、目标、计划交易、资金分配 |
|
| 类别细分、预算与实际对比、主要收款人、收入与支出对比 |
|
| 审计信用卡付款类别余额,采用先试运行、后确认应用的流程 |
开发
npm run dev # Watch mode with tsx
npm run build # Compile TypeScript
npm start # Run compiled server许可证
MIT
Available Tools
47 toolsaudit_credit_card_paymentsAudit Credit Card PaymentsA
[Variable API calls] [Workflow] Audits credit card payment categories by comparing each card's month-end balance against the payment category's available balance. Recommends exact budgeted amount corrections, accounting for cascading effects across months. Audit costs 3 + C + M API calls (C = credit cards, M = months). Set apply=true to automatically fix mismatches (adds 1 API call per mismatch).
Inputs: budget_id, since_month, account_id, apply.
create_accountCreate AccountB
[1 API call] Create a new account in a budget
Inputs: name (required), type (required), balance (required), budget_id.
create_categoryCreate CategoryB
[1 API call] Create a new category in a budget
Inputs: name (required), category_group_id (required), budget_id, note, +2 more.
create_category_groupCreate Category GroupA
[1 API call] Create a new category group in a budget
Inputs: name (required), budget_id.
create_scheduled_transactionCreate Scheduled TransactionA
[1 API call] Create a new scheduled (recurring) transaction. Date must be in the future (up to 5 years).
Inputs: account_id (required), date (required), amount (required), frequency (required), +6 more.
create_transactionCreate TransactionA
[1 API call] Create a new transaction. Amounts are in dollars (positive for inflows, negative for outflows). For split transactions, set category_id to null and provide subtransactions.
Inputs: account_id (required), date (required), amount (required), budget_id, +8 more.
create_transactionsCreate Multiple TransactionsA
[1 API call, bulk] Create multiple transactions at once. Each transaction needs account_id, date, and amount at minimum.
Inputs: transactions (required), budget_id.
delete_scheduled_transactionDelete Scheduled TransactionBDestructive
[1 API call] Delete a scheduled transaction
Inputs: scheduled_transaction_id (required), budget_id.
delete_transactionDelete TransactionBDestructive
[1 API call] Delete a transaction
Inputs: transaction_id (required), budget_id.
get_accountGet AccountBRead-only
[1 API call] Get details for a single account
Inputs: account_id (required), budget_id.
get_api_usageGet API UsageARead-only
[0 API calls] Check current YNAB API usage against the 200 calls/hour rate limit. Use this before batch operations to ensure you have enough budget.
Inputs: no named parameters.
get_budgetGet BudgetARead-only
[1 API call] Get a single budget's full detail including all entities. Use 'last-used' for the most recently accessed budget.
Inputs: budget_id, last_knowledge_of_server.
get_budget_settingsGet Budget SettingsBRead-only
[1 API call] Get a budget's date and currency format settings
Inputs: budget_id.
get_categoryGet CategoryBRead-only
[1 API call] Get details for a single category
Inputs: category_id (required), budget_id.
get_monthGet Budget MonthARead-only
[1 API call] Get detailed info for a single budget month including all category balances. Use 'current' for the current month.
Inputs: month (required), budget_id.
get_month_categoryGet Month CategoryBRead-only
[1 API call] Get a category's budget details for a specific month
Inputs: month (required), category_id (required), budget_id.
get_month_money_movement_groupsGet Month Money Movement GroupsBRead-only
[1 API call] Get money movement groups for a specific month
Inputs: month (required), budget_id.
get_month_money_movementsGet Month Money MovementsBRead-only
[1 API call] Get money movements for a specific month
Inputs: month (required), budget_id.
get_payeeGet PayeeBRead-only
[1 API call] Get details for a single payee
Inputs: payee_id (required), budget_id.
get_payee_locationGet Payee LocationBRead-only
[1 API call] Get a single payee location by ID
Inputs: payee_location_id (required), budget_id.
get_payee_locations_for_payeeGet Locations for PayeeBRead-only
[1 API call] Get all GPS locations for a specific payee
Inputs: payee_id (required), budget_id.
get_scheduled_transactionGet Scheduled TransactionBRead-only
[1 API call] Get details for a single scheduled transaction
Inputs: scheduled_transaction_id (required), budget_id.
get_transactionGet TransactionBRead-only
[1 API call] Get details for a single transaction
Inputs: transaction_id (required), budget_id.
get_userGet UserBRead-only
[1 API call] Get the authenticated user's information including user ID
Inputs: no named parameters.
import_transactionsImport TransactionsB
[1 API call] Trigger an import of transactions from linked financial institutions
Inputs: budget_id.
list_accountsList AccountsARead-only
[1 API call] List all accounts for a budget including balances and types
Inputs: budget_id, last_knowledge_of_server.
list_account_transactionsList Account TransactionsBRead-only
[1 API call] List transactions for a specific account
Inputs: account_id (required), budget_id, since_date, type, +1 more.
list_budgetsList BudgetsARead-only
[1 API call] List all budgets the user has access to, with optional account info
Inputs: include_accounts.
list_categoriesList CategoriesBRead-only
[1 API call] List all categories grouped by category group for a budget
Inputs: budget_id, last_knowledge_of_server.
list_category_transactionsList Category TransactionsBRead-only
[1 API call] List transactions for a specific category
Inputs: category_id (required), budget_id, since_date, type, +1 more.
list_money_movement_groupsList Money Movement GroupsBRead-only
[1 API call] List all money movement groups for a budget
Inputs: budget_id.
list_money_movementsList Money MovementsBRead-only
[1 API call] List all money movements for a budget (funds moved between categories)
Inputs: budget_id.
list_monthsList Budget MonthsARead-only
[1 API call] List all budget months for a budget, showing income, budgeted, activity, and ready to assign
Inputs: budget_id, last_knowledge_of_server.
list_month_transactionsList Month TransactionsBRead-only
[1 API call] List transactions for a specific month
Inputs: month (required), budget_id, since_date, type, +1 more.
list_payee_locationsList Payee LocationsBRead-only
[1 API call] List all payee GPS locations for a budget
Inputs: budget_id.
list_payeesList PayeesBRead-only
[1 API call] List all payees for a budget
Inputs: budget_id, last_knowledge_of_server.
list_payee_transactionsList Payee TransactionsBRead-only
[1 API call] List transactions for a specific payee
Inputs: payee_id (required), budget_id, since_date, type, +1 more.
list_scheduled_transactionsList Scheduled TransactionsBRead-only
[1 API call] List all scheduled (recurring) transactions for a budget
Inputs: budget_id, last_knowledge_of_server.
list_transactionsList TransactionsARead-only
[1 API call] List transactions for a budget with optional filters. Returns most recent transactions first.
Inputs: budget_id, since_date, type, last_knowledge_of_server.
merge_categoryMerge CategoryADestructive
[Variable API calls] [Workflow] Merges a source category into a target category: re-categorizes all transactions and moves all historical budgeted amounts. Dry run costs 4 + N calls (N = number of budget months). Execution costs additional 1 + 2*M calls (M = months with non-zero budgets). Defaults to dry_run=true to preview changes before executing. After merging, the source category will have zero transactions and zero budgeted amounts across all months - you can then manually hide/delete it in the YNAB app.
Inputs: source_category_id (required), target_category_id (required), budget_id, dry_run.
update_categoryUpdate CategoryB
[1 API call] Update an existing category's name, note, or goal
Inputs: category_id (required), budget_id, name, note, +2 more.
update_category_groupUpdate Category GroupB
[1 API call] Update a category group's name
Inputs: category_group_id (required), name (required), budget_id.
update_month_categoryUpdate Month Category BudgetA
[1 API call] Update the budgeted/assigned amount for a category in a specific month. This is how you allocate money to categories.
Inputs: month (required), category_id (required), budgeted (required), budget_id.
update_payeeUpdate PayeeB
[1 API call] Update a payee's name
Inputs: payee_id (required), name (required), budget_id.
update_scheduled_transactionUpdate Scheduled TransactionB
[1 API call] Update an existing scheduled transaction
Inputs: scheduled_transaction_id (required), account_id (required), date (required), budget_id, +7 more.
update_transactionUpdate TransactionC
[1 API call] Update an existing transaction
Inputs: transaction_id (required), budget_id, account_id, date, +8 more.
update_transactionsBulk Update TransactionsA
[1 API call, bulk] Update multiple transactions at once. Each must include either id or import_id to identify the transaction.
Inputs: transactions (required), budget_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 47 tools
Most tools have distinct purposes targeting specific resources and actions (e.g., get_account vs. list_accounts), but some overlap exists between list_transactions and more specific listing tools like list_account_transactions, which could cause confusion. The audit_credit_card_payments and merge_category workflows are clearly specialized, reducing ambiguity.
Tool names follow a highly consistent verb_noun pattern throughout, such as create_account, get_budget, list_transactions, and update_category. The two workflow tools (audit_credit_card_payments, merge_category) maintain this structure with descriptive nouns, ensuring predictability across all 47 tools.
With 47 tools, the count is excessive for a budgeting server, leading to a heavy and potentially overwhelming interface. While YNAB's API is comprehensive, many tools (e.g., get_payee_location, list_money_movement_groups) could be consolidated or omitted without losing core functionality, making the set feel bloated.
The tool set provides complete CRUD and lifecycle coverage for YNAB's domain, including accounts, categories, transactions, budgets, and payees. It also includes advanced workflows like auditing and merging, along with utility tools for API usage, ensuring no obvious gaps for agent operations.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
The Ramp MCP server enables users to securely connect Ramp with AI assistants like ChatGPT and Claude to query financial data and take actions using natural language. It transforms Ramp's developer API into a SQL interface that LLMs can query, allowing admins to analyze spend trends, identify cost savings, and run complex SQL analyses on comprehensive datasets (transactions, purchase orders, vendors, users), while all users can manage cards, view transactions, request reimbursements, and get expense policy answers.
Related MCP Servers
- FlicenseAqualityBmaintenanceAn MCP server that provides Large Language Models with access to YNAB (You Need A Budget) budgets, allowing them to fetch budget data including accounts, categories, and category groups.326-
- AlicenseAqualityDmaintenanceA minimal and auditable MCP server that enables local AI assistants to read and manage YNAB budget data. It supports operations like listing accounts, tracking transactions, and moving money between categories while maintaining user privacy.9MIT
- AlicenseCqualityCmaintenanceExposes YNAB API endpoints as MCP tools, allowing AI assistants to manage budgets, accounts, transactions, and more through natural language.41279 PyPI101MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that connects AI assistants to YNAB budgets, enabling natural language queries about finances backed by full API coverage and built-in YNAB methodology knowledge.1MIT