This MCP server lets Claude Code talk to your YNAB accounts through a secure OAuth flow, exposing budget management, transactions, insights, and advanced category features via a Docker-hosted MCP endpoint. You can run it locally, connect it to Claude Code, and use natural language commands to manage budgets, track transactions, and get financial guidance.

How to use

You run the MCP server in Docker and connect it to Claude Code using an MCP configuration. Once connected, you can view budgets and transactions, ask for insights, and manage your budget through conversational prompts. The server exposes a set of tools for budgets, accounts, transactions, categories, and AI-powered allocations.

How to install

Prerequisites you need before starting:

• Docker is installed and running on your machine
• Node.js v18+ is available for development and building (not required to run the production container)
• Claude Code CLI is installed and configured
• YNAB account credentials are ready to authorize OAuth flows

Install and run steps you will follow to deploy the MCP server locally:

# 1. Clone the project repository
# (Use the official project clone URL)
git clone <project-repo-url>
cd <project-directory>

# 2. Build the Docker image for the MCP server
# This will create the ynab-mcp:latest image
docker build -t ynab-mcp:latest .

# 3. Prepare data and config directories
# Ensure these paths exist on your system
mkdir -p /path/to/data
mkdir -p /path/to/config

# 4. Run the MCP server container
# This uses a Docker run command that mounts data/config and sets production mode
``````json
{
  "command": "docker",
  "args": [
    "run",
    "--rm",
    "-i",
    "-v",
    "/path/to/data:/app/data",
    "-v",
    "/path/to/config:/app/config",
    "-e",
    "NODE_ENV=production",
    "ynab-mcp:latest"
  ]
}

5. Authenticate with YNAB when prompted by Claude Code

# Optionally, register the MCP with Claude Code CLI using the provided JSON configuration
# Example if you create a config.json with the exact command;
claude mcp add-json ynab "$(cat config.json)"
```}]}},{

Configuration and security

Key points about how the MCP server operates and keeps your data secure:

• Tokens are stored securely in a mounted Docker volume to avoid leaking credentials.
• OAuth 2.0 is used for authentication with YNAB, and sensitive data is not logged.
• You can enable a read-only mode if you want to limit actions.
• The server implements a cache to improve performance while respecting YNAB rate limits (200 requests per hour).

Implementation highlights and known issues

This MCP server is built with Node.js and uses the official MCP SDK inside a Docker container. It integrates with the YNAB JavaScript SDK to perform budget management, transactions, and insights. It includes advanced category management features such as assigning allocations to multiple categories and AI-powered distribution recommendations.

Known issues you may encounter include transaction date parsing in the transactions endpoint and incomplete tool registration for all endpoints. Ongoing fixes are tracked in development branches focused on transactions accuracy and MCP tool registration.

Tools and capabilities overview

This MCP exposes a set of capabilities to manage finances via Claude Code. The primary tool areas include authentication, budgets, accounts, transactions, categories, and insights. Each tool enables natural language commands to interact with your YNAB data.

Available tools

authenticate

Authenticate with YNAB using OAuth 2.0 to obtain access tokens for API calls.

viewBudgets

List budgets, accounts, and budgets’ overview information.

listTransactions

Query transactions with filters and retrieve details for a budget.

createTransaction

Create and categorize a new transaction within a budget.

manageCategories

Add, assign, and optimize categories and allocations across budgets.

getInsights

Retrieve financial insights and AI-assisted recommendations for budget distribution.

cache

Cache results to improve performance while respecting API rate limits.