What can you do with this server?

This server provides read and write access to YNAB budgeting data via the Model Context Protocol. * Budgets: List all budgets, retrieve budget settings (date/currency formats). * Accounts: List all accounts, get a single account with balance, type, and on-budget status. * Categories: List all categories grouped by category group, get a single category with budgeted/activity/balance details, set a category's budgeted (assigned) amount, update category name/note/hidden status. * Payees: List all payees, get a single payee, rename a payee. * Months: List all budget months with summary info, get a single month's detailed data. * Transactions: List transactions with optional filters (by account, category, payee, or type), get a single transaction, create single or bulk transactions (with dry-run preview), update transaction fields (account, amount, date, payee, category, memo, cleared, approved), delete transactions. * Scheduled Transactions: List all scheduled transactions with frequency and next date, get a single scheduled transaction (including subtransactions), create scheduled transactions (with frequency validation), update scheduled transaction fields, delete scheduled transactions. * User: Get the authenticated user's ID.

How do I use py-ynab-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@py-ynab-mcp Show my transactions for the current 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.

py-ynab-mcp

by duganth

Overview Schema Source Related Servers Discussions Admin

Python

Remote

py-ynab-mcp

A Model Context Protocol server for YNAB (You Need A Budget). Talk to your budget from Claude, Cursor, or any MCP client.

Features

Query budgets, accounts, categories, transactions, payees, and months
Get single-resource details (account, category, payee, transaction)
Create, update, and delete transactions (single and bulk)
Create categories; update or clear targets, metadata, and budgets
Rename payees
Manage scheduled transactions (full CRUD)
Budget settings and user info

Related MCP server: YNAB MCP Server

Install

uvx py-ynab-mcp

Or with pip:

pip install py-ynab-mcp

Setup

Get a YNAB Personal Access Token
Add to your MCP client config:

{
  "mcpServers": {
    "ynab": {
      "command": "uvx",
      "args": ["py-ynab-mcp"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Why this project?

There are several YNAB MCP servers out there:

Project	Language	License
calebl/ynab-mcp-server	TypeScript	MIT
mattweg/ynab-mcp	JavaScript	MIT
chrisguidry/you-need-an-mcp	Python	No license
py-ynab-mcp	Python	MIT

We wanted an MIT-licensed Python implementation with full API coverage and thorough test coverage. At the time of writing, the only Python option had no OSS license, so we built this one.

YNAB API Coverage

Read

User info, budget settings
Budgets, accounts, categories, payees, months (list and single)
Transactions with filtering by account, category, or payee
Scheduled transactions (list and single)

Write

Create, update, delete transactions (single and bulk)
Create categories; update or clear targets, metadata, and budgets
Rename payees
Create, update, delete scheduled transactions

Not available in YNAB API

Create/delete budgets or accounts; delete categories
Create/delete payees (auto-created via transactions)
Transaction import

Development

# Clone and install
git clone https://github.com/duganth/py-ynab-mcp.git
cd py-ynab-mcp
uv sync

# Run tests
uv run pytest

# Lint and type check
uv run ruff check .
uv run mypy src/

License

MIT

Available Tools

27 tools

clear_category_targetA

Remove a category target without changing its assigned money.

Args: category_id: Category UUID. budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without clearing the target.

Inputs: category_id (required), dry_run, budget_id. Returns: result

create_categoryA

Create a category in a YNAB category group.

Args: category_group_id: Category group UUID. name: Category name. note: Optional category note. target_amount: Optional positive target amount in dollars. target_date: Optional target date in YYYY-MM-DD format. target_needs_whole_amount: Whether the entire target is needed. target_frequency: Optional target recurrence: monthly, weekly, or yearly. Cannot be combined with target_date. budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without creating.

Inputs: name (required), category_group_id (required), note, dry_run, +5 more. Returns: result

create_scheduled_transactionA

Create a scheduled (recurring) transaction in YNAB.

Args: account_id: Account UUID. amount: Dollar amount ("-42.50" for outflow, "100.00" for inflow). date: First occurrence date (YYYY-MM-DD). frequency: Recurrence frequency. Only single-word values work via the YNAB API: "never", "daily", "weekly", "monthly", "yearly". Multi-word camelCase values (everyOtherWeek, twiceAMonth, etc.) are documented but rejected by YNAB's own backend — set those manually in the YNAB UI. payee_name: Payee name. category_id: Category UUID. memo: Transaction memo. flag_color: Flag color. budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without creating.

Inputs: date (required), amount (required), frequency (required), account_id (required), +6 more. Returns: result

create_transactionA

Create a transaction in YNAB.

Args: account_id: Account UUID. amount: Dollar amount ("-42.50" for outflow, "100.00" for inflow). date: Transaction date (YYYY-MM-DD). payee_name: Payee name (YNAB auto-creates new payees). payee_id: Payee UUID, including an account transfer payee ID. category_id: Category UUID. Omit when splitting. memo: Transaction memo. cleared: "cleared", "uncleared", or "reconciled". approved: Whether the transaction is approved. subtransactions_json: JSON array of split legs, to record one card charge against several categories. Each element: {"amount", "category_id"?, "payee_name"?, "payee_id"?, "memo"?}. Amounts are dollars with the same sign as the parent (e.g. "-30.00") and must sum to it. Needs at least two legs, and category_id must be left off the parent. budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without creating.

Inputs: date (required), amount (required), account_id (required), memo, +8 more. Returns: result

create_transactionsA

Create multiple transactions in YNAB in a single API call.

Preferred over create_transaction when creating multiple transactions to minimize rate limit usage.

Args: transactions_json: JSON array of transactions. Each element: {"account_id", "amount", "date", "payee_name"?, "payee_id"?, "category_id"?, "memo"?, "cleared"?, "approved"?}. Amounts are in dollars (e.g. "-42.50"). budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without creating.

Inputs: transactions_json (required), dry_run, budget_id. Returns: result

delete_scheduled_transactionA

Delete a scheduled transaction from YNAB.

Args: scheduled_transaction_id: Scheduled transaction UUID. budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without deleting.

Inputs: scheduled_transaction_id (required), dry_run, budget_id. Returns: result

delete_transactionB

Delete a transaction from YNAB.

Args: transaction_id: Transaction UUID to delete. budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without deleting.

Inputs: transaction_id (required), dry_run, budget_id. Returns: result

get_accountA

Get a single YNAB account with full details.

Returns balance, type, on-budget status, note, and more.

Args: account_id: Account UUID. budget_id: Budget ID. Defaults to last-used budget.

Inputs: account_id (required), budget_id. Returns: result

get_budget_settingsA

Get budget settings including date and currency format.

Args: budget_id: Budget ID. Defaults to last-used budget.

Inputs: budget_id. Returns: result

get_categoryA

Get a single YNAB category with budget details.

Returns budgeted, activity, balance, and metadata.

Args: category_id: Category UUID. budget_id: Budget ID. Defaults to last-used budget.

Inputs: category_id (required), budget_id. Returns: result

get_monthA

Get a single budget month with per-category breakdown.

Returns the month summary (income, budgeted, activity, available) plus every category's budgeted/activity/balance.

Args: month: Month to retrieve (YYYY-MM-DD, first of month, e.g. "2026-03-01") or "current" for the current month. budget_id: Budget ID. Defaults to last-used budget.

Inputs: month (required), budget_id. Returns: result

get_payeeC

Get a single YNAB payee.

Args: payee_id: Payee UUID. budget_id: Budget ID. Defaults to last-used budget.

Inputs: payee_id (required), budget_id. Returns: result

get_scheduled_transactionA

Get details of a single scheduled transaction.

Returns full detail including subtransactions if present.

Args: scheduled_transaction_id: Scheduled transaction UUID. budget_id: Budget ID. Defaults to last-used budget.

Inputs: scheduled_transaction_id (required), budget_id. Returns: result

get_transactionB

Get a single YNAB transaction with full details.

Args: transaction_id: Transaction UUID. budget_id: Budget ID. Defaults to last-used budget.

Inputs: transaction_id (required), budget_id. Returns: result

get_userA

Get the authenticated YNAB user.

Returns the user ID.

Inputs: no named parameters. Returns: result

list_accountsA

List all accounts for a YNAB budget with balances.

Args: budget_id: Budget ID to list accounts for. If not provided, uses the default budget.

Inputs: budget_id. Returns: result

list_budgetsA

List all budgets for the authenticated YNAB user.

Returns budget names, IDs, date ranges, and last modified dates. Use the budget ID with other tools to target a specific budget.

Inputs: no named parameters. Returns: result

list_monthsA

List all budget months with summary figures.

Returns each month's income, budgeted, activity, available (to-be-budgeted), and age of money.

Args: budget_id: Budget ID. If not provided, uses the default budget.

Inputs: budget_id. Returns: result

list_payeesA

List all payees for a YNAB budget.

Returns payee names and IDs.

Args: budget_id: Budget ID to list payees for. If not provided, uses the default budget.

Inputs: budget_id. Returns: result

list_scheduled_transactionsB

List all scheduled transactions for a YNAB budget.

Returns each scheduled transaction with its frequency, next date, amount, payee, and category.

Args: budget_id: Budget ID. If not provided, uses the default budget.

Inputs: budget_id. Returns: result

list_transactionsA

List transactions from YNAB with optional filters.

Returns transactions since the given date. Optionally filter by one of: account, category, or payee (mutually exclusive).

Args: since_date: Start date (YYYY-MM-DD). Required. account_id: Filter by account UUID. category_id: Filter by category UUID. payee_id: Filter by payee UUID. type: Filter by "uncategorized" or "unapproved". budget_id: Budget ID. Defaults to last-used budget.

Inputs: since_date (required), type, payee_id, budget_id, +2 more. Returns: result

update_categoryA

Update category metadata or target configuration in YNAB.

Only provide the fields you want to change.

Args: category_id: Category UUID. name: New category name. note: New category note. category_group_id: New category group UUID. target_amount: Positive target amount in dollars. target_date: Target date in YYYY-MM-DD format. target_needs_whole_amount: Whether the entire target is needed. target_frequency: Target recurrence: monthly, weekly, or yearly. Cannot be combined with target_date. budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without updating.

Inputs: category_id (required), name, note, dry_run, +6 more. Returns: result

update_category_budgetA

Set the budgeted (assigned) amount for a category in a specific month.

Args: category_id: Category UUID. month: Month to update (YYYY-MM-DD, first of month, e.g. "2026-03-01"). amount: Dollar amount to assign (e.g. "500.00"). budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without updating.

Inputs: month (required), amount (required), category_id (required), dry_run, +1 more. Returns: result

update_payeeA

Update a YNAB payee (rename).

Args: payee_id: Payee UUID. name: New name for the payee. budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without updating.

Inputs: name (required), payee_id (required), dry_run, budget_id. Returns: result

update_scheduled_transactionA

Update fields of an existing scheduled transaction.

Only provide the fields you want to change.

Args: scheduled_transaction_id: Scheduled transaction UUID. account_id: New account UUID. amount: New dollar amount. date: New first date (YYYY-MM-DD). frequency: New frequency. Only single-word values work via the YNAB API: "never", "daily", "weekly", "monthly", "yearly". Multi-word values are rejected by YNAB's backend — change those in the UI. payee_name: New payee name. category_id: New category UUID. memo: New memo. flag_color: New flag color. budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without updating.

Inputs: scheduled_transaction_id (required), date, memo, amount, +7 more. Returns: result

update_transactionA

Update fields of an existing YNAB transaction.

Only provide the fields you want to change.

Args: transaction_id: Transaction UUID to update. account_id: New account UUID. amount: New dollar amount ("-42.50" for outflow). date: New date (YYYY-MM-DD). payee_name: New payee name. payee_id: New payee UUID, including an account transfer payee ID. category_id: New category UUID. Omit when splitting. memo: New memo. cleared: "cleared", "uncleared", or "reconciled". approved: Whether the transaction is approved. subtransactions_json: JSON array of split legs, converting this into a split transaction. Each element: {"amount", "category_id"?, "payee_name"?, "payee_id"?, "memo"?}. Amounts are dollars with the same sign as the parent and must sum to it. Pass amount too, so the legs can be checked against the total. Replaces any existing legs. budget_id: Budget ID. Defaults to last-used budget. dry_run: Validate and preview without updating.

Inputs: transaction_id (required), date, memo, amount, +9 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored 2026-09-09 18:36 across 27 tools

Disambiguation4/5

Most tools target a distinct resource and action, and singular/plural pairs like get_transaction vs list_transactions are predictable. The only real ambiguity is create_transaction vs create_transactions, but the description explicitly guides users to the plural version for batch creation.

Naming Consistency5/5

All tool names consistently follow snake_case verb_noun patterns: list_*, get_*, create_*, update_*, delete_*. Plural nouns are used only for list operations, and verb choice is uniform across resources.

Tool Count3/5

27 tools is heavy, but it reflects the wide YNAB domain: transactions, scheduled transactions, categories, payees, accounts, budgets, and months. Each tool has a clear role, though the set is large enough to add navigation overhead.

Completeness4/5

Transactions and scheduled transactions have full CRUD coverage, and categories/payees/accounts have solid read and write operations. Minor gaps like no account creation or category deletion exist, but the main YNAB budgeting workflows are covered without dead ends.

Maintenance

ActivitySlowing

ResponsivenessSyncing

Resources

Related MCP Connectors

ynab-mcp-server
com.smirnovlabs
Hosted remote MCP server for YNAB on Cloudflare Workers with OAuth
Finance
13
https://mcpforynab.smirnovlabs.com/mcp
Bonsave
app.bonsave
Query your real net worth, spending, transactions, budgets and portfolio from any MCP client.
Finance
1
https://www.bonsave.app/api/mcp
thoughts
ai.thoughtbox.api
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Cloud Storage Finance
2
https://api.thoughtbox.ai/mcp
Cite Caddy
dk.herbertkokholm.citecaddy
Remote MCP server for full read/write access to a Zotero library
Research & Data Knowledge & Memory
1
https://citecaddy.herbertkokholm.dk/mcp

Related MCP Servers

MCP YNAB Server
Finance Data Platforms
klauern
A
license
A
quality
B
maintenance
An MCP server that allows users to interact with YNAB data, enabling access to account balances, transactions, and the creation of new transactions through the Model Context Protocol.
Updated 2 months ago (2026-08-30 02:03 UTC)
8
6
MIT
YNAB MCP Server
Finance Agent Orchestration
calebl
A
license
A
quality
A
maintenance
A Model Context Protocol server that enables AI-powered interaction with YNAB (You Need A Budget) data, allowing users to query their budgets through conversational interfaces.
Updated a day ago (2026-11-09 10:56 UTC)
22
553 npm
165
MIT
ynab-mcp
Finance Databases App Automation
EthanKang1
A
license
Not graded
quality
D
maintenance
A Model Context Protocol (MCP) server for interacting with YNAB (You Need A Budget). Provides tools for accessing budget data through MCP-enabled clients like Claude Desktop.
Updated 2 years ago (2025-04-20 01:52 UTC)
4
MIT
YNAB MCP Server
Finance App Automation
ntdef
A
license
Not graded
quality
D
maintenance
A Model Context Protocol server that enables interaction with You Need A Budget (YNAB) via their API, allowing users to manage budgets, accounts, categories, and transactions through natural language.
Updated 2 years ago (2025-04-23 04:55 UTC)
2
MIT

py-ynab-mcp

Features

Install

Setup

Why this project?

YNAB API Coverage

Read

Write

Not available in YNAB API

Development

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

MCP YNAB Server

YNAB MCP Server

ynab-mcp

YNAB MCP Server