Skip to main content
Glama
ynab-mcp

ynab-mcp

by chadlis

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 token

  • ynab_list_accounts — accounts, balances, on/off-budget and transfer_payee_id

  • ynab_list_categories — category groups with budgeted / activity / balance

  • ynab_list_payees — payees (paginated)

  • ynab_list_transactions — transactions with filters (account, category, date range, type, payee text, exact amount, account name); optional split lines

  • ynab_get_transaction — every field of one transaction, including split lines

  • ynab_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 call

  • ynab_split_transaction — split an existing (e.g. imported) transaction in place

  • ynab_delete_transaction — delete a transaction (confirm=true required)

  • 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

  • uv

  • 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" budget

Run it:

uv run ynab-mcp

Use 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-mcp

Deploy to FastMCP Cloud

This server is built with the fastmcp package, so it deploys as-is on FastMCP Cloud:

  1. Push this repo to GitHub, then connect it as a project on fastmcp.cloud.

  2. Set the entrypoint to src/ynab_mcp/server.py:mcp.

  3. Add YNAB_TOKEN (and optionally YNAB_BUDGET_ID) as an environment variable/secret in the project settings — dependencies are picked up automatically from pyproject.toml.

You can validate the entrypoint locally first:

uv run fastmcp inspect src/ynab_mcp/server.py:mcp

Conventions

  • Amounts are in normal currency units; an expense is negative (e.g. -12.50). Conversion to/from YNAB milliunits is automatic.

  • budget_id defaults to YNAB_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 .    # lint

Security

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 tools
ynab_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 summaryA
Read-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 accountsA
Read-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 budgetsA
Read-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 categoriesA
Read-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 payeesA
Read-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 transactionsA
Read-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 transactionA
Idempotent

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

    A4.3/5.0

    Scored across 8 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    All tool names follow the pattern `ynab_<verb>_<noun>` in snake_case, e.g., `ynab_create_transaction`, `ynab_list_accounts`. Consistent and predictable.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      12
      23 npm
      2
      GPL 3.0
    • A
      license
      B
      quality
      A
      maintenance
      Enables 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.
      45
      439 npm
      48
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Provides 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.
      10
      12 npm
      MIT