YNAB MCP Server
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 How much is left in my Groceries budget for this month?"
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
MCP server for YNAB (You Need A Budget) — manage budgets, accounts, categories, and transactions through Claude.
Tools
Core (daily budget management)
Tool | Description |
| List all budgets |
| List accounts with balances |
| Category groups with budgeted/activity/balance |
| List payees (for resolving names to IDs) |
| Monthly overview with per-category breakdown |
| Search transactions by date/account/category/payee |
| Add a new transaction |
| Change budgeted amount for a category |
Extended (weekly/occasional)
Tool | Description |
| Edit existing transaction fields |
| Delete a transaction |
| Create multiple transactions from JSON |
| View recurring/upcoming bills |
| Add a new account |
| Historical month list for trends |
| Change category name, note, or goal |
Related MCP server: YNAB Assistant
Setup
1. Get a YNAB Personal Access Token
Go to YNAB Settings > Developer Settings and create a Personal Access Token.
2. Configure environment
cp .env.example .env
# Edit .env and set YNAB_ACCESS_TOKEN3. Run locally
# stdio transport (Claude Desktop / Claude Code)
uv run server.py
# HTTP transport (Claude.ai connector / remote access)
uv run server.py --transport streamable-http4. Claude Desktop configuration
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"ynab": {
"command": "uv",
"args": ["run", "/path/to/ynab-mcp/server.py"],
"env": {
"YNAB_ACCESS_TOKEN": "your-token-here"
}
}
}
}Deployment (Railway)
Push this repo to GitHub
Create a new Railway project and connect the repo
Set environment variables in Railway:
YNAB_ACCESS_TOKEN— your YNAB Personal Access TokenYNAB_DEFAULT_BUDGET_ID— (optional) default budget UUID or "last-used"MCP_BEARER_TOKEN— (optional) secure the MCP endpoint
Railway auto-deploys on push to
main
The server reads the PORT environment variable (set automatically by Railway).
Multi-User Support
Set per-user tokens to give each person their own connector URL:
YNAB_TOKEN_ADAM=adams-token
YNAB_TOKEN_SARAH=sarahs-tokenURL routing:
/adam/mcp— usesYNAB_TOKEN_ADAM/sarah/mcp— usesYNAB_TOKEN_SARAH/mcp— usesYNAB_ACCESS_TOKEN(default)
Currency Format
YNAB uses milliunits (1/1000 of a currency unit):
$10.00=10000milliunits-$5.50=-5500milliunits
All tool responses include both raw milliunit values and formatted display strings (e.g., balance and balance_display).
Rate Limits
YNAB allows 200 requests per hour per access token. The server returns friendly error messages when rate limited (HTTP 429).
Available Tools
15 toolscreate_accountA
Create a new account in a budget.
Args: name: Account name (e.g., "Chase Checking"). type: Account type. One of: checking, savings, cash, creditCard, lineOfCredit, otherAsset, otherLiability, mortgage, autoLoan, studentLoan, personalLoan, medicalDebt, otherDebt. balance: Starting balance in milliunits (e.g., 100000 = $100.00). budget_id: Budget ID (uses default if omitted).
Returns: Created account details with id, name, type, and balance.
Inputs: name (required), type (required), balance (required), budget_id. Returns: result
create_transactionA
Create a new transaction.
Args: account_id: The account UUID to create the transaction in. date: Transaction date in YYYY-MM-DD format. amount: Amount in milliunits (negative for outflows, positive for inflows). Example: -50000 = -$50.00 outflow, 150000 = $150.00 inflow. payee_name: Name of payee (creates new payee if doesn't exist). Use this OR payee_id. payee_id: UUID of existing payee. Use this OR payee_name. category_id: UUID of the budget category. Omit when using subtransactions (each sub has its own). memo: Transaction memo. cleared: Cleared status: "cleared", "uncleared", or "reconciled". Defaults to "cleared". approved: Whether the transaction is approved. Defaults to True. flag_color: Optional flag: red, orange, yellow, green, blue, purple. subtransactions: Array of subtransaction objects for split transactions. Each item: {"amount": int, "category_id": "uuid", "memo": "text", "payee_id": "uuid", "payee_name": "text"}. Only amount and category_id are required per sub. The sub amounts must sum to the parent amount. When using subtransactions, omit category_id on the parent (it becomes a split). budget_id: Budget ID (uses default if omitted).
Returns: Created transaction details with id, date, amount, payee, category, and subtransactions.
Inputs: account_id (required), date (required), amount (required), payee_name, +8 more. Returns: result
create_transactions_bulkA
Create multiple transactions at once from a JSON string.
The JSON should contain a "transactions" array where each item has: account_id (required), date (required), amount (required in milliunits), and optionally: payee_name, payee_id, category_id, memo, cleared, approved, flag_color, subtransactions (array of {amount, category_id, memo, payee_id, payee_name}).
Args: transactions_json: JSON string with a "transactions" array. budget_id: Budget ID (uses default if omitted).
Returns: Summary of created and duplicate transactions.
Inputs: transactions_json (required), budget_id. Returns: result
delete_transactionB
Delete a transaction.
Args: transaction_id: The transaction UUID to delete. budget_id: Budget ID (uses default if omitted).
Returns: Confirmation of deletion.
Inputs: transaction_id (required), budget_id. Returns: result
get_accountsA
List all accounts in a budget with balances.
Args: budget_id: Budget ID (uses default if omitted).
Returns: List of accounts with name, type, balance, cleared_balance, on_budget, and closed status.
Inputs: budget_id. Returns: result
get_budget_monthsA
List all months in a budget with summary data.
Useful for trend analysis — see how income, spending, and budgeting have changed over time.
Args: budget_id: Budget ID (uses default if omitted).
Returns: List of months with income, budgeted, activity, to_be_budgeted, age_of_money.
Inputs: budget_id. Returns: result
get_budgetsA
List all budgets the user has access to.
Args: include_accounts: If True, include account summaries for each budget.
Returns: List of budgets with id, name, last_modified_on, and currency format.
Inputs: include_accounts. Returns: result
get_categoriesA
List all category groups and categories with budgeted/activity/balance for the current month.
Args: budget_id: Budget ID (uses default if omitted).
Returns: Category groups with nested categories showing budgeted, activity, balance, and goal info.
Inputs: budget_id. Returns: result
get_monthA
Get a monthly budget summary with category breakdowns.
Args: month: Month in YYYY-MM-DD format (first of month, e.g., "2026-02-01"). Defaults to current month. budget_id: Budget ID (uses default if omitted).
Returns: Month overview: income, budgeted, activity, to_be_budgeted, age_of_money, plus per-category details.
Inputs: month, budget_id. Returns: result
get_payeesB
List all payees in a budget.
Args: budget_id: Budget ID (uses default if omitted).
Returns: List of payees with id and name.
Inputs: budget_id. Returns: result
get_scheduled_transactionsB
List all scheduled (recurring) transactions.
Args: budget_id: Budget ID (uses default if omitted).
Returns: List of scheduled transactions with frequency, next date, amount, payee, category.
Inputs: budget_id. Returns: result
get_transactionsA
Search and list transactions with optional filters.
Args: budget_id: Budget ID (uses default if omitted). since_date: Only return transactions on or after this date (YYYY-MM-DD). before_date: Only return transactions before this date (YYYY-MM-DD). Server-side filter. Use with since_date for a date range, e.g. since_date="2024-02-01", before_date="2024-03-01" for all February 2024 transactions. type: Filter by "uncategorized" or "unapproved". account_id: Filter to a specific account. category_id: Filter to a specific category. payee_id: Filter to a specific payee. max_results: Maximum transactions to return (default 200).
Returns: List of transactions with date, amount, payee, category, memo, cleared status. Includes truncated flag and total_available count when results are capped.
Inputs: budget_id, since_date, before_date, type, +4 more. Returns: result
update_categoryB
Update a category's name, note, or goal target.
Args: category_id: The category UUID. name: New category name. note: New category note. goal_target: New goal target in milliunits (e.g., 500000 = $500.00). budget_id: Budget ID (uses default if omitted).
Returns: Updated category details.
Inputs: category_id (required), name, note, goal_target, +1 more. Returns: result
update_month_categoryA
Update the budgeted amount for a category in a specific month.
Use this to move money between categories or adjust budget allocations.
Args: category_id: The category UUID to update. budgeted: New budgeted amount in milliunits (e.g., 50000 = $50.00). month: Month in YYYY-MM-DD format (first of month). Defaults to current month. budget_id: Budget ID (uses default if omitted).
Returns: Updated category with new budgeted amount, activity, and balance.
Inputs: category_id (required), budgeted (required), month, budget_id. Returns: result
update_transactionA
Update an existing transaction.
Args: transaction_id: The transaction UUID to update. account_id: Move to a different account. date: New date (YYYY-MM-DD). amount: New amount in milliunits. payee_name: New payee name. payee_id: New payee UUID. category_id: New category UUID. memo: New memo. cleared: New cleared status: "cleared", "uncleared", or "reconciled". approved: New approved status. flag_color: New flag color: red, orange, yellow, green, blue, purple. subtransactions: Array of subtransaction objects to convert this into a split transaction. Each item: {"amount": int, "category_id": "uuid", "memo": "text", "payee_id": "uuid", "payee_name": "text"}. Only amount and category_id are required per sub. The sub amounts must sum to the parent amount. When adding subtransactions, also provide the new parent amount if changing it. budget_id: Budget ID (uses default if omitted).
Returns: Updated transaction details.
Inputs: transaction_id (required), account_id, date, amount, +9 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 15 tools
Each tool has a distinct purpose targeting specific resources and actions, such as create_account for accounts, get_transactions for listing, and update_month_category for budget adjustments. No significant overlap exists; even create_transaction and create_transactions_bulk are clearly differentiated by single vs. bulk operations.
All tool names follow a consistent verb_noun pattern, using verbs like create, get, update, and delete paired with specific nouns like account, transaction, or category. This uniformity makes the tool set predictable and easy to navigate.
With 15 tools, the server covers core budgeting operations comprehensively without being overwhelming. This count is well-suited for the domain, providing essential CRUD and query functions for accounts, transactions, budgets, categories, and payees.
The tool set offers complete coverage for personal finance management, including CRUD for accounts and transactions, budget and category management, payee handling, and month-level operations. No obvious gaps exist; agents can perform end-to-end budgeting workflows seamlessly.
Related MCP Connectors
Ask Claude about your income and spending, and import bank statements. No bank login.
Log, query, and edit expenses, budgets, and accounts in Manilo (formerly Ledgy) from any MCP-compatible AI assistant.
Run Apple Search Ads from Claude: performance, recommendations, keywords, budgets, launches.
Personal finance, bank account, and shared memory connector for Claude, ChatGPT, Gemini Spark & more
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to help manage your You Need A Budget (YNAB) finances through comprehensive budget operations. Supports account management, transaction handling, category budgeting, split transactions, scheduled payments, and spending analytics with robust error handling and automatic retry logic.214MIT
- 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
- AlicenseCqualityCmaintenanceExposes YNAB API endpoints as MCP tools, allowing AI assistants to manage budgets, accounts, transactions, and more through natural language.41198 PyPI100MIT