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
- AsecurityFlicenseAqualityAn MCP server that allows users to interact with YNAB data, enabling access to account balances, transactions, and the creation of new transactions through the Model Context Protocol.Last updated -101Python
- -securityFlicense-qualityProvides 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 -Python
- 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 -1151TypeScriptMIT License
- -securityFlicense-qualityA Model Context Protocol server that enables Claude AI to interact with the Solana blockchain, allowing it to execute transactions, query accounts, manage wallets, get price predictions, trade tokens, and access various blockchain data sources.Last updated -2