YNAB MCP Server
This server gives an AI assistant read/write access to your YNAB budget (plans, accounts, categories, payees, months, money movements, transactions, and scheduled transactions) through the YNAB API.
User: view the authenticated user's info (
getUser).Plans: list plans with optional accounts, and read plan settings; use
last-usedordefaultasplan_id.Accounts: list accounts, get one by id, and create accounts (checking, savings, cash, credit card, asset, liability) with balances.
Categories: list categories grouped by group; get a category or a category for a specific month; create/update categories (names, notes, goal targets, frequencies, dates, groups); update monthly assigned amounts; create/update category groups.
Payees: get, create, and update payees; list payee locations overall, by id, or by payee.
Months: list all plan months and read a single month (including "current").
Money movements: list money movements and movement groups, overall or by month.
Transactions: list transactions (filtered by
type,since_date,until_date, server knowledge), get one by id, create single or bulk transactions (including splits and import IDs), update one or many, delete, and list by account, category, payee, or month. Large results are guarded with an error prompting narrower date ranges.Scheduled transactions: list, get, create, update, and delete recurring scheduled transactions with frequencies and future dates.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@YNAB MCP Server Show me my budgets"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
YNAB MCP Server
An MCP server for the YNAB API, built with FastMCP.
Tools are generated at startup from YNAB's published OpenAPI spec, so new YNAB endpoints show up without a new release of this package.
Setup
Install uv.
Create a YNAB personal access token at app.ynab.com/settings/developer (New Token). Copy it right away; YNAB only shows it once.
Add the server to your MCP client using one of the snippets below, replacing
your-token-herewith your token.
Every snippet runs uvx ynab-mcp-tools, which downloads the package from PyPI and runs it in an isolated environment. You don't need to clone this repository.
Claude Code
claude mcp add ynab --scope user \
-e "YNAB_API_TOKEN=your-token-here" \
-- uvx ynab-mcp-toolsDrop --scope user to add it to the current project only. See the Claude Code MCP docs.
Codex
codex mcp add ynab \
--env "YNAB_API_TOKEN=your-token-here" \
-- uvx ynab-mcp-toolsClaude Desktop and Cursor
Both use the same JSON. Add it to:
Claude Desktop:
~/Library/Application Support/Claude/claude_desktop_config.json(macOS) or%APPDATA%\Claude\claude_desktop_config.json(Windows)Cursor:
~/.cursor/mcp.json(global) or.cursor/mcp.json(project)
{
"mcpServers": {
"ynab": {
"command": "uvx",
"args": ["ynab-mcp-tools"],
"env": {
"YNAB_API_TOKEN": "your-token-here"
}
}
}
}To find the Claude Desktop config file without typing the path, open Settings → Desktop App → Extensions (Manage) → Local MCP Servers → Edit Config. Finder opens with the file selected. On macOS, right-click it and choose Open With → TextEdit, paste the JSON above, save, then quit and reopen Claude Desktop.
ChatGPT desktop app
Open Settings, search for "MCP", and click MCPs / Plugins.
Click Add → Add MCP Server and fill in:
Name:
YNABCommand to launch:
uvxArguments:
ynab-mcp-toolsEnvironment Variables: key
YNAB_API_TOKEN, valueyour-token-here
If a desktop app reports that it can't find uvx, replace uvx with the full path printed by which uvx in a terminal (usually ~/.local/bin/uvx, written out as /Users/<you>/.local/bin/uvx).
OpenCode
Add to ~/.config/opencode/opencode.json:
{
"mcp": {
"servers": {
"ynab": {
"type": "local",
"command": ["uvx", "ynab-mcp-tools"],
"environment": {
"YNAB_API_TOKEN": "your-token-here"
}
}
}
}
}Related MCP server: YNAB MCP Server
Tools
YNAB's API now calls budgets plans, so tools and parameters use that name (getPlans, plan_id). Pass last-used as the plan_id to target your most recently opened plan.
Area | Tools |
User |
|
Plans |
|
Accounts |
|
Categories |
|
Payees |
|
Months |
|
Money movements |
|
Transactions |
|
Scheduled transactions |
|
Two kinds of endpoints are left out on purpose:
getPlanByIdandgetPayees: these return an entire plan export or the full payee list, which is too large for a model's context. The narrower tools above cover the same data.Endpoints YNAB marks deprecated, such as
importTransactions, which YNAB now accepts but ignores.
YNAB's API has no pagination. The transaction list tools tell the model to pass since_date, until_date, or type, and if a transaction list still comes back over 200,000 characters, the tool returns an error asking the model to retry with a narrower range.
Example prompts
"Show me my unapproved transactions from the last two weeks."
"How much have I spent on dining out this month compared to last month?"
"Categorize my uncategorized transactions, and ask me about anything ambiguous."
"Move $50 from Vacation to Groceries for this month."
To make your own conventions stick between sessions (how you handle Venmo duplicates, which payees map to which categories), write them into your client's skills or rules, for example a Claude skill.
Resources
License
MIT
Available Tools
41 toolscreateAccountCreateaccountC
Creates a new account
Inputs: account (required), plan_id (required).
createCategoryCreatecategoryC
Creates a new category
Inputs: plan_id (required), category (required).
createCategoryGroupCreatecategorygroupC
Creates a new category group
Inputs: plan_id (required), category_group (required).
createPayeeCreatepayeeC
Creates a new payee
Inputs: payee (required), plan_id (required).
createScheduledTransactionCreatescheduledtransactionC
Creates a single scheduled transaction (a transaction with a future date).
Inputs: plan_id (required), scheduled_transaction (required).
createTransactionCreatetransactionA
Creates a single transaction or multiple transactions. If you provide a body containing a transaction object, a single transaction will be created and if you provide a body containing a transactions array, multiple transactions will be created. Scheduled transactions (transactions with a future date) cannot be created on this endpoint.
Inputs: plan_id (required), transaction, transactions.
deleteScheduledTransactionDeletescheduledtransactionC
Deletes a scheduled transaction
Inputs: plan_id (required), scheduled_transaction_id (required).
deleteTransactionDeletetransactionD
Deletes a transaction
Inputs: plan_id (required), transaction_id (required).
getAccountByIdGetaccountbyidC
Returns a single account
Inputs: plan_id (required), account_id (required).
getAccountsGetaccountsC
Returns all accounts
Inputs: plan_id (required), last_knowledge_of_server.
getCategoriesGetcategoriesA
Returns all categories grouped by category group. Amounts (assigned, activity, available, etc.) are specific to the current plan month (UTC).
Inputs: plan_id (required), last_knowledge_of_server.
getCategoryByIdGetcategorybyidB
Returns a single category. Amounts (assigned, activity, available, etc.) are specific to the current plan month (UTC).
Inputs: plan_id (required), category_id (required).
getMoneyMovementGroupsGetmoneymovementgroupsC
Returns all money movement groups
Inputs: plan_id (required).
getMoneyMovementGroupsByMonthGetmoneymovementgroupsbymonthC
Returns all money movement groups for a specific month
Inputs: month (required), plan_id (required).
getMoneyMovementsGetmoneymovementsC
Returns all money movements
Inputs: plan_id (required).
getMoneyMovementsByMonthGetmoneymovementsbymonthB
Returns all money movements for a specific month
Inputs: month (required), plan_id (required).
getMonthCategoryByIdGetmonthcategorybyidA
Returns a single category for a specific plan month. Amounts (assigned, activity, available, etc.) are specific to the current plan month (UTC).
Inputs: month (required), plan_id (required), category_id (required).
getPayeeByIdGetpayeebyidC
Returns a single payee
Inputs: plan_id (required), payee_id (required).
getPayeeLocationByIdGetpayeelocationbyidC
Returns a single payee location
Inputs: plan_id (required), payee_location_id (required).
getPayeeLocationsGetpayeelocationsC
Returns all payee locations
Inputs: plan_id (required).
getPayeeLocationsByPayeeGetpayeelocationsbypayeeC
Returns all payee locations for a specified payee
Inputs: plan_id (required), payee_id (required).
getPlanMonthGetplanmonthC
Returns a single plan month
Inputs: month (required), plan_id (required).
getPlanMonthsGetplanmonthsC
Returns all plan months
Inputs: plan_id (required), last_knowledge_of_server.
getPlansGetplansC
Returns plans list with summary information
Inputs: include_accounts.
getPlanSettingsByIdGetplansettingsbyidB
Returns settings for a plan
Inputs: plan_id (required).
getScheduledTransactionByIdGetscheduledtransactionbyidB
Returns a single scheduled transaction
Inputs: plan_id (required), scheduled_transaction_id (required).
getScheduledTransactionsGetscheduledtransactionsC
Returns all scheduled transactions
Inputs: plan_id (required), last_knowledge_of_server.
getTransactionByIdGettransactionbyidC
Returns a single transaction
Inputs: plan_id (required), transaction_id (required).
getTransactionsGettransactionsA
Returns plan transactions, excluding any pending transactions
IMPORTANT: this can return thousands of transactions and overflow your context. Always pass since_date (and until_date when you know it) covering only the dates you need, such as the last 7 to 30 days. Without since_date, YNAB returns a full year. Pass type="unapproved" or type="uncategorized" when you only need those transactions.
Inputs: plan_id (required), type, since_date, until_date, +1 more.
getTransactionsByAccountGettransactionsbyaccountA
Returns all transactions for a specified account, excluding any pending transactions
IMPORTANT: this can return thousands of transactions and overflow your context. Always pass since_date (and until_date when you know it) covering only the dates you need, such as the last 7 to 30 days. Without since_date, YNAB returns a full year. Pass type="unapproved" or type="uncategorized" when you only need those transactions.
Inputs: plan_id (required), account_id (required), type, since_date, +2 more.
getTransactionsByCategoryGettransactionsbycategoryA
Returns all transactions for a specified category, excluding any pending transactions
IMPORTANT: this can return thousands of transactions and overflow your context. Always pass since_date (and until_date when you know it) covering only the dates you need, such as the last 7 to 30 days. Without since_date, YNAB returns a full year. Pass type="unapproved" or type="uncategorized" when you only need those transactions.
Inputs: plan_id (required), category_id (required), type, since_date, +2 more.
getTransactionsByMonthGettransactionsbymonthA
Returns all transactions for a specified month, excluding any pending transactions
IMPORTANT: this can return thousands of transactions and overflow your context. Always pass since_date (and until_date when you know it) covering only the dates you need, such as the last 7 to 30 days. Without since_date, YNAB returns a full year. Pass type="unapproved" or type="uncategorized" when you only need those transactions.
Inputs: month (required), plan_id (required), type, since_date, +2 more.
getTransactionsByPayeeGettransactionsbypayeeA
Returns all transactions for a specified payee, excluding any pending transactions
IMPORTANT: this can return thousands of transactions and overflow your context. Always pass since_date (and until_date when you know it) covering only the dates you need, such as the last 7 to 30 days. Without since_date, YNAB returns a full year. Pass type="unapproved" or type="uncategorized" when you only need those transactions.
Inputs: plan_id (required), payee_id (required), type, since_date, +2 more.
getUserGetuserB
Returns authenticated user information
Inputs: no named parameters.
updateCategoryUpdatecategoryD
Update a category
Inputs: plan_id (required), category (required), category_id (required).
updateCategoryGroupUpdatecategorygroupD
Update a category group
Inputs: plan_id (required), category_group (required), category_group_id (required).
updateMonthCategoryUpdatemonthcategoryC
Update a category for a specific month. Only budgeted (assigned) amount can be updated.
Inputs: month (required), plan_id (required), category (required), category_id (required).
updatePayeeUpdatepayeeD
Update a payee
Inputs: payee (required), plan_id (required), payee_id (required).
updateScheduledTransactionUpdatescheduledtransactionD
Updates a single scheduled transaction
Inputs: plan_id (required), scheduled_transaction (required), scheduled_transaction_id (required).
updateTransactionUpdatetransactionC
Updates a single transaction
Inputs: plan_id (required), transaction (required), transaction_id (required).
updateTransactionsUpdatetransactionsC
Updates multiple transactions, by id or import_id.
Inputs: plan_id (required), transactions (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 41 tools
Most tools target a distinct resource+action pair, and the transaction-scoped variants (byAccount, byCategory, byPayee, byMonth) are meaningfully differentiated by their filter. Some overlap remains between getTransactions and its filtered siblings, and the PlanMonth/MonthCategory/money-movement cluster (getPlanMonth, getMonthCategoryById, getMoneyMovementsByMonth) requires careful reading to pick correctly.
Names follow a predictable camelCase verb_noun pattern (get*/update*/create*/delete* + resource), including plural forms for bulk operations (updateTransactions vs updateTransaction). Minor inconsistency in resource vocabulary: the same concept is called 'PlanMonth' in getPlanMonth(s) but 'MonthCategory' in getMonthCategoryById, and 'Plans' vs 'planSettings'.
41 tools is heavy for an agent-facing surface and exceeds the comfortable range, though it largely mirrors the breadth of the underlying YNAB API across accounts, transactions, categories, payees, scheduled transactions, months, and money movements. A few areas (four money-movement tools, three payee-location tools) look like thin API passthroughs rather than earn-your-place tools.
Transactions have full lifecycle coverage, but the surface is uneven elsewhere: there is no way to list payees (only getPayeeById), and no delete operations for accounts, categories, category groups, or payees, so agents can create resources they cannot clean up. Some lookups are also missing (e.g. money movement by id, scheduled transactions filtered by account).
Maintenance
Related MCP Connectors
Log, query, and edit expenses, budgets, and accounts in Manilo from any MCP-compatible AI assistant.
Log, query, and edit expenses, budgets, and accounts in Manilo (formerly Ledgy) from any MCP-compatible AI assistant.
Log, query, and edit expenses, budgets, and accounts in Ledgy from any MCP-compatible AI assistant.
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with YNAB budgets through natural language. Supports managing accounts, categories, transactions, and budget months with 21 tools for comprehensive budget operations.-
- AlicenseAqualityDmaintenanceEnables interaction with You Need A Budget (YNAB) through their API, allowing users to manage budgets, accounts, categories, transactions, payees, and scheduled transactions through natural language.1223 npm2GPL 3.0
- AlicenseAqualityBmaintenanceAn MCP server that exposes the full YNAB API, allowing LLMs to read and manage budgets, accounts, and transactions through natural language. It features 49 specialized tools for comprehensive financial management, including category updates, money movements, and transaction tracking.47208 npmMIT
- AlicenseAqualityCmaintenanceConnects AI assistants to YNAB budgets, providing over 30 tools for managing budgets, accounts, transactions, categories, and analytics with delta sync and caching.47141 PyPI48AGPL 3.0