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:
- Transactions API - The
list_transactions
endpoint fails with "invalid date" errors when using thesinceDate
parameter - Missing API Tools - Several endpoints that are defined in the source code are not available in the MCP integration
- 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 APIfix-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
- Clone this repository
- Copy
config/config.example.js
toconfig/config.js
and add your YNAB API credentials - Build the Docker image:
docker build -t ynab-mcp:latest .
- Create a JSON configuration for Claude:
- Register the MCP with Claude Code CLI:You can also save the JSON to a file and use:
- 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
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A Model Context Protocol server that enables Claude Code to interact with You Need A Budget (YNAB) accounts, providing API access for budget management, transaction tracking, and financial insights through OAuth authentication.
Related MCP Servers
- -securityFlicense-qualityA Model Context Protocol server that enables Claude AI to interact with Paybyrd's payment processing API, allowing for creating payment links, processing refunds, and retrieving order information.Last updated -2TypeScript
- AsecurityFlicenseAqualityProvides access to YNAB (You Need A Budget) functionality through the Model Context Protocol, allowing users to view account balances, access transaction data, and create new transactions.Last updated -10Python
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI-powered interaction with YNAB (You Need A Budget) data, allowing users to query their budgets through conversational interfaces.Last updated -1321TypeScriptMIT License
- -securityAlicense-qualityA Model Context Protocol (MCP) server for interacting with YNAB (You Need A Budget). Provides tools for accessing budget data through MCP-enabled clients like Claude Desktop.Last updated -1PythonMIT License