A Model Context Protocol (MCP) server that exposes YNAB (You Need A Budget) budget data to LLMs like Claude.

• List all YNAB budgets with details
• Secure authentication using YNAB API tokens
• Simple resource-based interface via MCP

• Python 3.11 or higher
• uv package manager
• A YNAB account with API access

1. Get your YNAB API Token

   Visit https://app.ynab.com/settings/developer to generate a personal access token.

2. Set the environment variable

   export YNAB_API_TOKEN="your_token_here"

   Or create a .env file (see .env.example):

   cp .env.example .env # Edit .env and add your token

3. Install dependencies

   Dependencies are already configured in pyproject.toml. When you run the server with uv, it will automatically install them.

export YNAB_API_TOKEN="your_token" uv run mcp dev src/ynab_mcp/server.py

Add the following to your Claude Code MCP settings (~/.claude.json):

{ "mcpServers": { "ynab": { "command": "uvx", "args": ["--from", "git+https://github.com/greatgitsby/ynab-mcp", "ynab-mcp"], "env": { "YNAB_API_TOKEN": "your_token_here" } } } }

After installation, Claude Code will be able to access your YNAB budgets through the ynab://budgets resource.

If you have the repo cloned locally:

uv run mcp install src/ynab_mcp/server.py --name "YNAB"

Run the comprehensive test script:

./test.sh

This script will automatically load your .env file and run all tests.

Or run the integration test directly:

export YNAB_API_TOKEN="your_token" uv run python tests/integration_test.py

This will:

1. Start the MCP server
2. Connect to it as a client
3. List available resources
4. Read the budgets resource
5. Validate the response

Lists all budgets for the authenticated user.

Returns: Formatted text with budget details including:

• Budget name
• Budget ID
• Last modified date
• Currency information

ynab-mcp/ ├── src/ │ └── ynab_mcp/ │ ├── __init__.py # Package initialization │ ├── server.py # MCP server with FastMCP │ └── client.py # YNAB API client ├── tests/ │ └── integration_test.py # Integration test ├── test.sh # Test runner script ├── pyproject.toml # Project configuration ├── README.md # This file ├── .gitignore # Git ignore patterns └── .env.example # Environment variable template 

To add more YNAB endpoints:

1. Add methods to YNABClient in src/ynab_mcp/client.py
2. Create new resource handlers in src/ynab_mcp/server.py using @mcp.resource()
3. Update tests to cover the new functionality

The server handles common errors:

• Missing or invalid API token (401)
• Rate limiting (429)
• Network errors
• General API errors

For more information about the YNAB API:

• YNAB API Documentation
• OpenAPI Specification

This project is provided as-is for use with YNAB and Claude Code.