What is Ynab Mcp

ynab-mcp is a YNAB Model Context Protocol (MCP) server designed for integration with Claude Code, enabling interaction with YNAB (You Need A Budget) accounts.

Use cases

Use cases for ynab-mcp include automating personal budgeting tasks, creating financial reports, tracking expenses, and utilizing AI-driven recommendations for budget allocation.

How to use

To use ynab-mcp, ensure you have Docker and Node.js v18+ installed. Clone the repository, set up your YNAB account, and follow the installation instructions to get started with the API for budget management and transaction tracking.

Key features

Key features include OAuth-based authentication, complete budget and account management, transaction creation and categorization, advanced category management with bulk allocation and recommendations, support for multiple budgets, rate limit handling, and caching for improved performance.

Where to use

ynab-mcp can be used in personal finance management, budgeting applications, and any scenario where integration with YNAB is required for financial insights and transaction management.

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