ynab-mcp
This MCP server lets an MCP client read YNAB budget data and create/update transactions. Per the provided schema (which exposes fewer tools than the README):
List accessible budgets, including currency and last-modified date.
List accounts with balances, on-budget status, and closed flag.
List category groups/categories with budgeted, activity, and balance.
List payees with pagination.
List transactions with filters for account or category, since-date, transaction type, and pagination.
Get a monthly budget summary: to-be-budgeted, income, budgeted, activity, age of money.
Create a transaction with account, amount, payee, category, date, memo, cleared, and approved fields.
Partially update a transaction’s amount, payee, category, memo, cleared, or approved status.
Choose markdown or JSON response format for read tools.
Amounts are in currency units, with negative values for expenses; budget defaults to
last-used.
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 show me my recent transactions"
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
An MCP server that exposes your YNAB (You Need A Budget) budget to MCP clients such as Claude Desktop and claude.ai.
Tools
Read
ynab_list_budgets— budgets accessible with your tokenynab_list_accounts— accounts, balances, on/off-budget andtransfer_payee_idynab_list_categories— category groups with budgeted / activity / balanceynab_list_payees— payees (paginated)ynab_list_transactions— transactions with filters (account, category, date range, type, payee text, exact amount, account name); optional split linesynab_get_transaction— every field of one transaction, including split linesynab_get_budget_month— monthly summary (to-be-budgeted, income, activity, age of money)
Write
ynab_create_transaction— create a transaction, split and/or transfer (amount in currency units, negative = expense)ynab_update_transaction— partially update a transaction (categorize, approve, memo, flag, turn into a transfer…)ynab_update_transactions— update up to 100 transactions in one API callynab_split_transaction— split an existing (e.g. imported) transaction in placeynab_delete_transaction— delete a transaction (confirm=truerequired)ynab_set_category_budgeted/ynab_move_money— assign or move money between categories
Transfers: never pass payee_name="Transfer : X" (YNAB rejects it). Pass
transfer_account_name="X" (case, accents and emoji ignored) or transfer_account_id,
also inside split lines. A transfer from an on-budget account to an off-budget
(tracking) account requires a category_id; between on-budget accounts it takes none.
Related MCP server: YNAB MCP Server
Requirements
A YNAB Personal Access Token — YNAB → Account Settings → Developer Settings → New Token
Setup
uv sync # install dependencies
cp .env.example .env # then put your token in .env.env:
YNAB_TOKEN=your-token-here
YNAB_BUDGET_ID= # optional; empty = use YNAB's "last-used" budgetRun it:
uv run ynab-mcpUse with Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"ynab": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/ynab-mcp", "ynab-mcp"],
"env": { "YNAB_TOKEN": "your-token-here" }
}
}
}Remote (HTTP) hosting
Set MCP_TRANSPORT=http to serve over streamable-http (endpoint /mcp):
MCP_TRANSPORT=http HOST=0.0.0.0 PORT=8000 uv run ynab-mcpDeploy to FastMCP Cloud
This server is built with the fastmcp package, so
it deploys as-is on FastMCP Cloud:
Push this repo to GitHub, then connect it as a project on fastmcp.cloud.
Set the entrypoint to
src/ynab_mcp/server.py:mcp.Add
YNAB_TOKEN(and optionallyYNAB_BUDGET_ID) as an environment variable/secret in the project settings — dependencies are picked up automatically frompyproject.toml.
You can validate the entrypoint locally first:
uv run fastmcp inspect src/ynab_mcp/server.py:mcpConventions
Amounts are in normal currency units; an expense is negative (e.g.
-12.50). Conversion to/from YNAB milliunits is automatic.budget_iddefaults toYNAB_BUDGET_ID, or the"last-used"budget if unset.YNAB rate limit: 200 requests / hour / token. Batch tools report the remaining quota. Accounts are cached in memory for 10 minutes to resolve transfers without extra calls.
Development
uv sync --extra dev
uv run pytest # tests (HTTP mocked, no network)
uv run ruff check . # lintSecurity
Never commit .env — it contains a live token and is gitignored. If a token
leaks, rotate it in YNAB's Developer Settings.
License
MIT
Available Tools
8 toolsynab_create_transactionCreate a transactionA
Create a transaction in an account.
The amount is given in normal currency units (e.g. -12.50 for a 12.50 expense); conversion to milliunits is automatic. Returns the new id.
Inputs: amount (required), account_id (required), memo, cleared, +5 more. Returns: result
ynab_get_budget_monthMonth summaryARead-onlyIdempotent
Budget summary for a month: to be budgeted, income, budgeted, activity, age of money.
Inputs: month, budget_id, response_format. Returns: result
ynab_list_accountsList accountsARead-onlyIdempotent
List a budget's accounts with their balance (converted to currency units).
Returns: id, name, type, on_budget (bool), current balance, closed flag.
Inputs: budget_id, include_closed, response_format. Returns: result
ynab_list_budgetsList budgetsARead-onlyIdempotent
List the YNAB budgets accessible with this token, with their currency.
Returns for each budget: id, name, currency iso_code, last modified date. Useful to grab a specific budget_id (otherwise use "last-used" elsewhere).
Inputs: response_format. Returns: result
ynab_list_categoriesList categoriesARead-onlyIdempotent
List category groups and their categories, with budgeted / activity / balance.
Each category: id, name, budgeted, activity, balance (all in currency units). Needed to grab a category_id before creating/categorizing a transaction.
Inputs: budget_id, response_format. Returns: result
ynab_list_payeesList payeesARead-onlyIdempotent
List a budget's payees, paginated.
Returns id + name. Useful to find the id of a recurring merchant.
Inputs: limit, offset, budget_id, response_format. Returns: result
ynab_list_transactionsList transactionsARead-onlyIdempotent
List a budget's transactions, with filters and pagination.
Filter by account OR by category (not both, per the API), by date (since_date) and by type (uncategorized / unapproved). Amount is in currency units (negative = expense). Returns id, date, payee_name, amount, category_name, memo, approved, cleared.
Inputs: limit, offset, txn_type, budget_id, +4 more. Returns: result
ynab_update_transactionUpdate a transactionAIdempotent
Partially update a transaction (categorize, approve, fix a memo…).
Only the provided fields change. Typical case: assign category_id + approved=true to an imported, uncategorized transaction.
Inputs: transaction_id (required), memo, amount, cleared, +4 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct operation: creating, listing, updating transactions, listing budgets, accounts, categories, payees, and retrieving budget month data. No two tools overlap in purpose.
All tool names follow the pattern `ynab_<verb>_<noun>` in snake_case, e.g., `ynab_create_transaction`, `ynab_list_accounts`. Consistent and predictable.
With 8 tools covering core CRUD and listing operations for budgets, accounts, categories, payees, and transactions, the count is well-scoped for a personal finance server.
Covers essential operations: create/update/list transactions, list budgets/accounts/categories/payees, and get budget month. Missing delete transaction is a minor gap, but typical workflows are supported.
Maintenance
Related MCP Connectors
The budget app your AI agent can use. Check budgets and log spending, with no bank logins.
Read your accounts, budgets and net worth, and draft changes you confirm.
Personal finance by conversation: expenses, receipts, statement import, budgets, net worth.
Log, query, and edit expenses, budgets, and accounts in Manilo from any MCP-compatible AI assistant.
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
- AlicenseBqualityAmaintenanceEnables AI assistants to interact with YNAB budgets, performing read-only queries by default and optional write operations like creating transactions and managing categories through natural language.45439 npm48MIT
- AlicenseAqualityCmaintenanceProvides a read-only interface to YNAB budget data, allowing AI assistants to inspect budgets, accounts, categories, transactions, and more. Includes an experimental guarded write workflow for category assignments.1012 npmMIT