YNAB

by klauern

1 Not rated yet

GitHub

About

Integrates with YNAB API to enable personal finance management, including viewing account balances, creating transactions, and accessing budget data for financial planning and analysis.

Details

Repository: klauern/mcp-ynab

Explore

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name YNAB

Command (node, npx, python, etc.) npx
Arguments
- Argument 1 -y
- Argument 2 @highlight/mcp-server
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "ynab": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "ynab": {
            "env": {},
            "args": [
                "/c",
                "npx",
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "ynab": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "ynab": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "ynab": {
            "env": {},
            "args": [
                "/c",
                "npx",
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "ynab": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "ynab": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "ynab": {
            "env": {},
            "args": [
                "/c",
                "npx",
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "ynab": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "ynab": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "ynab": {
            "env": {},
            "args": [
                "/c",
                "npx",
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "ynab": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "ynab": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "ynab": {
            "env": {},
            "args": [
                "/c",
                "npx",
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "ynab": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

From the repository

The project is managed with uv and
Task. All Python commands in this repo go through
uv run.

uv sync                  # install dependencies
task install             # install the mcp-ynab CLI into the venv

`search`

Discover available YNAB operations without live API access.

`execute`

Run a short Python snippet against the live YNAB API.

`ping`

Health check the server.

`get_preferences`

Inspect server preferences.

`set_preference`

Update preferences such as mutation or escape-hatch settings.

`set_api_key`

Store a YNAB API key in the OS keychain.

`clear_api_key`

Remove the stored YNAB API key.

`set_preferred_budget_id`

Cache a preferred budget ID for default-targeted calls.

`get_budgets`

List all budgets in markdown.

`get_accounts`

List accounts in a budget, grouped by type with summary.

`get_account_balance`

Return a single account's current balance in dollars.

`get_transactions`

Recent transactions for an account; optional `since_date`.

`get_transactions_needing_attention`

Filter for uncategorized / unapproved transactions.

`get_categories`

All categories in a budget grouped by category group.

`create_transaction`

Create a new transaction in YNAB.

`categorize_transaction`

Assign a category to an existing transaction.

`cache_categories`

Cache a budget's category list locally.

return [t for t in spec if "transaction" in t["name"]]



Execute a query:

python

return await ynab.read.get_budgets()



To access all ~34 direct YNAB tools, set the escape-hatch preference:

text
set_preference: code_mode_replace_tools = false



By default, the public MCP tool surface is intentionally small:
| Tool | Purpose |

| ---- | ------- |

| search | Discover available YNAB operations without live API access |

| execute | Run a short Python snippet against the live YNAB API |

| ping | Health check the server |

| get_preferences | Inspect server preferences |

| set_preference | Update preferences such as mutation or escape-hatch settings |

| set_api_key | Store a YNAB API key in the OS keychain |

| clear_api_key | Remove the stored YNAB API key |

| set_preferred_budget_id | Cache a preferred budget ID for default-targeted calls |
Use search to discover operations:

python
return [
{"name": tool["name"], "description": tool["description"]}
for tool in spec
if "category" in tool["name"]
]

Then call the operation through execute:

python
categories = await ynab.read.get_categories()
return [
{"name": category.name, "balance": category.balance}
for group in categories
for category in group.categories[:LIMIT]
]



Mutating operations live under ynab.write. and require

code_mode_mutations_enabled=true:

python
result = await ynab.write.bulk_categorize(assignments=assignments)
return result
``

The underlying direct tools still exist in the internal FastMCP registry so Code Mode can dispatch throughynab.read., generate stubs, and build the search catalog. They are hidden from the public tool list by default. Setcode_mode_replace_tools=falseto restore the full direct-tool surface as an escape hatch.


Representative internal direct tools include:
Read-only internal tools

| Tool | Purpose | | ---- | ------- | |get_budgets| List all budgets in markdown | |get_accounts| List accounts in a budget, grouped by type with summary | |get_account_balance| Return a single account's current balance in dollars | |get_transactions | Recent transactions for an account; optional since_date| |get_transactions_needing_attention| Filter for uncategorized / unapproved transactions | |get_categories | All categories in a budget grouped by category group |


Mutating internal tools

| Tool | Purpose | | ---- | ------- | |create_transaction| Create a new transaction in YNAB | |categorize_transaction| Assign a category to an existing transaction | |set_preferred_budget_id| Cache a preferred budget ID for default-targeted tools | |cache_categories | Cache a budget's category list locally |

For account transfers and credit-card payments, use the destination account's transfer payee ID aspayee_idwhen creating or updating a transaction. Theget_payees tool lists transfer payees with their Transfer Account ID. Do not pass aTransfer : ... value as payee_name; YNAB rejects or treats that as a regular payee instead of creating a linked transfer.


Resources

- ynab://preferences/budget_id— currently preferred budget ID -ynab://categories/{budget_id}— cached categories for a budget -ynab://code-mode/stubs— generated Python stubs for Code Mode -ynab://code-mode/examples` — curated Code Mode snippets

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "ynab": {
            "env": {},
            "args": [
                "-y",
                "@highlight/mcp-server"
            ],
            "command": "npx"
        }
    }
}

Linux

{
    "env": [],
    "args": [
        "-y",
        "@highlight/mcp-server"
    ],
    "command": "npx"
}

Macos

{
    "env": [],
    "args": [
        "-y",
        "@highlight/mcp-server"
    ],
    "command": "npx"
}

Windows

{
    "env": [],
    "args": [
        "/c",
        "npx",
        "-y",
        "@highlight/mcp-server"
    ],
    "command": "cmd"
}

mcp-ynab

A Model Context Protocol server for the
YNAB (You Need A Budget) API. Lets MCP clients (Claude
Desktop, Claude Code, custom agents) read your budgets, accounts, and
transactions, and create or recategorize transactions through structured tools.

Install

The project is managed with uv and
Task. All Python commands in this repo go through
uv run.

uv sync                  # install dependencies
task install             # install the mcp-ynab CLI into the venv

Configure

Set your YNAB Personal Access Token in the environment (or in a .env file at
the repo root):

export YNAB_API_KEY=your-personal-access-token

Get a token at <https://app.ynab.com/settings/developer>.

Quickstart

1. Set your API key

Code Mode is the default surface — it requires your YNAB API key:

export YNAB_API_KEY="your-key-here"

Or store it in your OS keychain (the server reads it automatically).

2. Use Code Mode

By default the server exposes two tools: search (discover available operations) and execute (run a snippet against the live YNAB API).

Discover tools:
```python

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Explore

Setting up with Highlight

From the repository

search

execute

ping

get_preferences

set_preference

set_api_key

clear_api_key

set_preferred_budget_id

get_budgets

get_accounts

get_account_balance

get_transactions

get_transactions_needing_attention

get_categories

create_transaction

categorize_transaction

cache_categories

Claude Desktop / Cursor

Linux

Macos

Windows

mcp-ynab

Install

Configure

Quickstart

1. Set your API key

2. Use Code Mode

More like this

Time

Sentry

Github

Git

`search`

`execute`

`ping`

`get_preferences`

`set_preference`

`set_api_key`

`clear_api_key`

`set_preferred_budget_id`

`get_budgets`

`get_accounts`

`get_account_balance`

`get_transactions`

`get_transactions_needing_attention`

`get_categories`

`create_transaction`

`categorize_transaction`

`cache_categories`