mcpField
Y
YNAB MCP

YNAB MCP

Local
github.com/mattwegFinance15Updated 7w ago
Repository

About YNAB MCP

YNAB MCP is a Docker-based server that connects Claude Code to You Need A Budget accounts for budget management and transaction tracking. It supports OAuth, bulk category allocation, and read-only mode; the README also notes issues with some transaction tools.

Key features

  1. 01Authenticate YNAB accounts with OAuth
  2. 02View and manage budgets and accounts
  3. 03Create and categorize transactions
  4. 04Allocate funds across categories and get suggestions
  5. 05Support caching and read-only mode

Use cases

  1. 01Review budgets and transactions
  2. 02Create transactions and organize categories
  3. 03Allocate funds to multiple budget categories
  4. 04Get allocation suggestions based on goals and spending

MCP support

The MCP server gives Claude Code access to YNAB budget, account, and transaction management capabilities. The README notes issues with some transaction API behavior and MCP tool registration.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "ynab-mcp-mattweg": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "NODE_ENV",
        "ynab-mcp:latest"
      ],
      "env": {
        "NODE_ENV": "<NODE_ENV>"
      }
    }
  }
}
Run commanddocker run -i --rm -e NODE_ENV ynab-mcp:latest
Environment variables to set
NODE_ENV

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
ociynab-mcp:latest

Tools

No tool list yet

Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.

Details

From the project README

YNAB MCP

YNAB Model Context Protocol (MCP) server for Claude Code integration with You Need A Budget (YNAB).

Overview

This repository contains a Docker-based MCP server that enables Claude Code to interact with YNAB (You Need A Budget) accounts. It implements the OAuth flow and provides a comprehensive API for budget management, transaction tracking, and financial insights.

Known Issues

MCP Tool Availability

The following issues have been identified:

  1. Transactions API - The list_transactions endpoint fails with "invalid date" errors when using the sinceDate parameter
  2. Missing API Tools - Several endpoints that are defined in the source code are not available in the MCP integration
  3. Inconsistent Behavior - Some tools work in testing with test-mcp.js but fail in the actual MCP integration
Issue Tracking

We're actively working on the following fixes:

  • fix-transactions-api branch: Addressing the date format handling in the transactions API
  • fix-mcp-registration branch: Ensuring all API tools are properly registered and available

Features

  • OAuth-based authentication with YNAB API
  • Complete budget and account management
  • Transaction creation and categorization
  • Advanced category management with bulk allocation and recommendations
  • Support for multiple budgets (personal and family)
  • Rate limit handling (YNAB API limit: 200 requests/hour)
  • Caching for improved performance
New Category Management Features

This MCP includes advanced category management capabilities:

  • Assign to Categories: Allocate funds from Ready to Assign to multiple categories in one operation
  • Recommended Allocations: Get AI-powered suggestions for budget distribution based on goals and spending patterns

See Category Management Documentation for details.

Getting Started

Prerequisites
  • Docker
  • Node.js v18+ (for development)
  • Claude Code CLI
  • YNAB account
Installation
  1. Clone this repository
  2. Copy config/config.example.js to config/config.js and add your YNAB API credentials
  3. Build the Docker image: docker build -t ynab-mcp:latest .
  4. Create a JSON configuration for Claude: 
    {
  "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. Register the MCP with Claude Code CLI: 
    claude mcp add-json ynab '{"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"]}'
    You can also save the JSON to a file and use: 
    claude mcp add-json ynab "$(cat config.json)"
  6. Authenticate with your YNAB account when prompted by Claude

Integration with Claude

This MCP integrates seamlessly with Claude, allowing:

  • Viewing budgets and transactions
  • Getting financial insights
  • Managing your budget through natural conversation

Security

  • Tokens are stored securely in a mounted Docker volume
  • No sensitive data is logged
  • Authentication uses OAuth 2.0 standards
  • Support for read-only mode

Implementation Details

The implementation follows the Model Context Protocol standard using:

  • Node.js and the official MCP SDK
  • Docker for containerization and deployment
  • YNAB JavaScript SDK for API operations
  • OAuth 2.0 for authentication

License

MIT

Acknowledgements

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.