playbooks

home / mcp / ynab mcp server

YNAB MCP Server

A FastMCP server that lets AI assistants interact with your YNAB budget through the Model Context Protocol.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "franccesco-ynab-mcp": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "YNAB_ACCESS_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}

You have a FastMCP server that exposes YNAB budget actions as modular tools you can call from AI assistants. This lets you ask questions about your budget, create or modify transactions, adjust categories, or review month details using natural language, all through a dedicated MCP endpoint you control.

How to use

You interact with this MCP server through a client that speaks the Model Context Protocol. When you start the server, it exposes an HTTP endpoint at /mcp and can also run locally as a stdio service. Use an MCP client to connect, then invoke tools by name to perform budget actions. Most common workflows include listing accounts, viewing or updating category budgets, creating transactions, and retrieving budget month details. For convenience, the server defaults to your last-used budget when you perform actions that require a budget context.

To perform an action, authorize your client with your YNAB access token and then call the relevant tool by its name. For example, you might request a list of accounts, add a new transaction, or fetch details for a specific budget month. The tools are designed to be used in natural language workflows, so you can combine multiple steps into a single conversation with your AI assistant.

How to install

Prerequisites: you need Python for this server and the uv command for running the MCP interface.

uv sync

Set your YNAB access token from your YNAB Developer Settings and export it to your environment.

export YNAB_ACCESS_TOKEN="your_token_here"

Alternatively, you can store the token in a local environment configuration file and load it automatically.

echo 'export YNAB_ACCESS_TOKEN="your_token_here"' > .envrc
 direnv allow

Start the MCP server so it becomes available at the MCP endpoint.

uv run python main.py

Configuration and notes

Important notes for running and using the server.

  • All amounts in milliunits (e.g., -50000 = -$50.00)
  • Most tools default to your last-used budget for convenience
  • Built with FastMCP and the YNAB SDK

Available tools

accounts_list

Retrieve a list of YNAB accounts available in the selected budget.

account_details

Get detailed information for a specific YNAB account by its ID.

categories_view

View budgets and notes for categories within a budget.

categories_update

Update budgets or notes for a specific category.

transactions_create

Create a new transaction in a chosen account or category.

transactions_read

Read details of a specific transaction by its ID.

transactions_update

Update fields of an existing transaction.

transactions_delete

Delete a transaction from the budget.

months_view

View details for a budget month, including spending and balances.

user_info

Retrieve information about the authenticated user.