Skip to main content
Glama
Sign In
ynab-mcp-server

ynab-mcp-server

by Gregarrific
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

ynab-mcp-server

A personal MCP server that gives Claude native access to YNAB budget data.

Architecture

Layer 1: FastMCP reads YNAB's official OpenAPI spec at startup and auto-generates one MCP tool per endpoint.

Layer 2: Custom tools for higher-level workflows: spending summaries by category, payee consolidation/renaming.

Related MCP server: monarch-mcp

Setup

Prerequisites

Install

uv sync

Configure

Create a .env file (never committed):

YNAB_API_TOKEN=your_token_here
YNAB_READ_ONLY=false

Run

YNAB_API_TOKEN=your_token uv run ynab-mcp-server

Connecting to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ynab": {
      "command": "/absolute/path/to/.venv/bin/ynab-mcp-server",
      "env": {
        "YNAB_API_TOKEN": "your_token_here",
        "YNAB_READ_ONLY": "false"
      }
    }
  }
}

Use the absolute path from which ynab-mcp-server after uv sync.

Environment Variables

Variable

Required

Description

YNAB_API_TOKEN

Yes

YNAB personal access token

YNAB_READ_ONLY

No

Set true to block all write operations

Testing

npx @modelcontextprotocol/inspector

Available Tools

46 tools
createAccountC

Creates a new account

Inputs: plan_id (required), account (required).

createCategoryC

Creates a new category

Inputs: plan_id (required), category (required).

createCategoryGroupC

Creates a new category group

Inputs: plan_id (required), category_group (required).

createPayeeC

Creates a new payee

Inputs: plan_id (required), payee (required).

createScheduledTransactionB

Creates a single scheduled transaction (a transaction with a future date).

Inputs: plan_id (required), scheduled_transaction (required).

createTransactionA

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.

deleteScheduledTransactionB

Deletes a scheduled transaction

Inputs: plan_id (required), scheduled_transaction_id (required).

deleteTransactionC

Deletes a transaction

Inputs: plan_id (required), transaction_id (required).

getAccountByIdB

Returns a single account

Inputs: plan_id (required), account_id (required).

getAccountsB

Returns all accounts

Inputs: plan_id (required), last_knowledge_of_server.

getCategoriesA

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.

getCategoryByIdA

Returns a single category. Amounts (assigned, activity, available, etc.) are specific to the current plan month (UTC).

Inputs: plan_id (required), category_id (required).

getMoneyMovementGroupsC

Returns all money movement groups

Inputs: plan_id (required).

getMoneyMovementGroupsByMonthC

Returns all money movement groups for a specific month

Inputs: plan_id (required), month (required).

getMoneyMovementsC

Returns all money movements

Inputs: plan_id (required).

getMoneyMovementsByMonthC

Returns all money movements for a specific month

Inputs: plan_id (required), month (required).

getMonthCategoryByIdA

Returns a single category for a specific plan month. Amounts (assigned, activity, available, etc.) are specific to the current plan month (UTC).

Inputs: plan_id (required), month (required), category_id (required).

getPayeeByIdB

Returns a single payee

Inputs: plan_id (required), payee_id (required).

getPayeeLocationByIdC

Returns a single payee location

Inputs: plan_id (required), payee_location_id (required).

getPayeeLocationsB

Returns all payee locations

Inputs: plan_id (required).

getPayeeLocationsByPayeeB

Returns all payee locations for a specified payee

Inputs: plan_id (required), payee_id (required).

getPayeesB

Returns all payees

Inputs: plan_id (required), last_knowledge_of_server.

getPlanByIdA

Returns a single plan with all related entities. This resource is effectively a full plan export.

Inputs: plan_id (required), last_knowledge_of_server.

getPlanMonthB

Returns a single plan month

Inputs: plan_id (required), month (required).

getPlanMonthsC

Returns all plan months

Inputs: plan_id (required), last_knowledge_of_server.

getPlansB

Returns plans list with summary information

Inputs: include_accounts.

getPlanSettingsByIdC

Returns settings for a plan

Inputs: plan_id (required).

getScheduledTransactionByIdB

Returns a single scheduled transaction

Inputs: plan_id (required), scheduled_transaction_id (required).

getScheduledTransactionsC

Returns all scheduled transactions

Inputs: plan_id (required), last_knowledge_of_server.

getTransactionByIdC

Returns a single transaction

Inputs: plan_id (required), transaction_id (required).

getTransactionsC

Returns plan transactions, excluding any pending transactions

Inputs: plan_id (required), since_date, until_date, type, +1 more.

getTransactionsByAccountB

Returns all transactions for a specified account, excluding any pending transactions

Inputs: plan_id (required), account_id (required), since_date, until_date, +2 more.

getTransactionsByCategoryA

Returns all transactions for a specified category, excluding any pending transactions

Inputs: plan_id (required), category_id (required), since_date, until_date, +2 more.

getTransactionsByMonthB

Returns all transactions for a specified month, excluding any pending transactions

Inputs: plan_id (required), month (required), since_date, until_date, +2 more.

getTransactionsByPayeeA

Returns all transactions for a specified payee, excluding any pending transactions

Inputs: plan_id (required), payee_id (required), since_date, until_date, +2 more.

getUserA

Returns authenticated user information

Inputs: no named parameters.

importTransactionsA

Imports available transactions on all linked accounts for the given plan. Linked accounts allow transactions to be imported directly from a specified financial institution and this endpoint initiates that import. Sending a request to this endpoint is the equivalent of clicking "Import" on each account in the web application or tapping the "New Transactions" banner in the mobile applications. The response for this endpoint contains the transaction ids that have been imported.

Inputs: plan_id (required).

updateCategoryC

Update a category

Inputs: plan_id (required), category_id (required), category (required).

updateCategoryGroupC

Update a category group

Inputs: plan_id (required), category_group_id (required), category_group (required).

updateMonthCategoryA

Update a category for a specific month. Only budgeted (assigned) amount can be updated.

Inputs: plan_id (required), month (required), category_id (required), category (required).

updatePayeeD

Update a payee

Inputs: plan_id (required), payee_id (required), payee (required).

updateScheduledTransactionC

Updates a single scheduled transaction

Inputs: plan_id (required), scheduled_transaction_id (required), scheduled_transaction (required).

updateTransactionC

Updates a single transaction

Inputs: plan_id (required), transaction_id (required), transaction (required).

updateTransactionsC

Updates multiple transactions, by id or import_id.

Inputs: plan_id (required), transactions (required).

ynab_consolidate_payeeConsolidate / Rename a PayeeA
Idempotent

Rename a payee and update all its transactions to use a canonical name.

Use this to clean up messy imported payee names:

  • "AMZN*1A2B3C4D" → "Amazon"

  • "WHOLEFDS MKT #123" → "Whole Foods"

  • Merge two duplicate payees into one

IMPORTANT — always call with preview_only=true first. This shows you exactly which transactions will be affected. Only set preview_only=false after reviewing and approving the preview.

How it works:

  1. Finds all transactions belonging to source_payee_id

  2. Renames the payee itself to target_name

  3. All linked transactions automatically reflect the new name

Note: YNAB does not have a "delete payee" endpoint. Renaming the payee is the correct approach — it handles deduplication internally.

Inputs: params (required). Returns: result

ynab_get_spending_summaryGet Spending Summary by CategoryA
Read-onlyIdempotent

Aggregate transactions by category and return ranked spending totals.

Use this to answer questions like:

  • "How much did I spend on dining out this month?"

  • "What are my top 10 spending categories this year?"

  • "Compare groceries vs restaurants for Q1"

Amounts are returned in dollars (not YNAB milliunits). Transfers and income are excluded — only outflows are shown.

Inputs: params (required). 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

    B3/5.0

    Scored across 46 tools

    Disambiguation5/5

    Each tool targets a specific resource and action (get, create, update, delete, import, consolidate, spend). Even similar getters are differentiated by filters (by account, category, month, payee), and the two custom ynab_ functions have unique purposes.

    Naming Consistency5/5

    All tools follow a consistent camelCase verb_noun pattern (e.g., getAccounts, createTransaction, updateCategory). The two ynab_ prefixed tools are the only exceptions but are clearly labeled as custom utilities.

    Tool Count4/5

    46 tools is high but justified by the complexity of YNAB's data model (accounts, categories, payees, transactions, plans, etc.). Each tool addresses a distinct endpoint, though some consolidation could reduce count slightly.

    Completeness3/5

    Core transaction and scheduled transaction CRUD is complete, but accounts lack update/delete endpoints, and categories lack delete. Plans only have read operations. The ynab_consolidate_payee workaround addresses missing payee deletion, but gaps remain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • ynab-mcp

      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.
      4
      MIT

    • monarch-mcp

      bkichler
      F
      license
      B
      quality
      D
      maintenance
      MCP server that bridges Claude to Monarch Money for personal-finance analysis and lightweight edits.
      18
      -

    • plaid-mcp-server

      lukew0824
      F
      license
      Not graded
      quality
      C
      maintenance
      A self-hosted MCP server that lets Claude query your bank accounts, balances, and transactions through Plaid.
      1
      -

    • ynab-mcp

      koonn
      A
      license
      B
      quality
      D
      maintenance
      A read-only MCP server for YNAB budgeting data, enabling daily/weekly/monthly expense reviews and planning support via Claude Desktop or Claude Code.
      4
      Apache 2.0