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

• YNAB API

• YNAB JavaScript Library

• Anthropic Claude