This server enables AI assistants to interact with You Need A Budget (YNAB) for comprehensive budget management and financial analysis. Key capabilities include:
Budget Management: View and manage multiple budgets, accounts, categories, and payees
Transaction Control: List, search, update, and schedule transactions
Financial Analysis: Get financial overviews, track spending patterns, and monitor budget progress
Fund Allocation: Move and assign budget amounts between categories
Data Cleaning: Merge and rename payees for cleaner data
Automation: Bulk update transactions and refresh financial overviews
Detailed Lookups: Find specific entity details by ID
Enables loading environment variables from a .env file for configuration, particularly for storing the YNAB Personal Access Token securely.
YNAB MCP Server
A Model Context Protocol (MCP) server for seamless integration with You Need A Budget (YNAB). This server enables AI assistants to interact with your YNAB budgets, providing powerful automation and analysis capabilities.
Quick Installation (Claude Desktop)
Optional environment variables:
Related MCP server: Letta Agents MCP Server
Features
Complete Budget Management
View and manage multiple budgets
Track account balances and transactions
Monitor category spending and goals
Transaction Control
List and search transactions
Update transaction details
Manage payees and categories
Financial Analysis
Get comprehensive financial overviews
Track spending patterns
Monitor budget progress
Table of Contents
Installation & Usage
No installation needed when using uvx:
For development:
Platform-Specific Setup
Claude Desktop
Locate your configuration file:
MacOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%/Claude/claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
Add the YNAB MCP server configuration:
Optional environment variables:
Goose
Open Goose settings
Navigate to the MCP Servers section
Add a new server with:
Name:
ynab-mcpCommand:
uvx ynab-mcp-serverEnvironment Variables:
YNAB_PAT: your_token_here
Other Platforms
For other MCP-compatible platforms, configure using these parameters:
Server Name:
ynab-mcpCommand:
uvxArguments:
ynab-mcp-serverRequired Environment Variable:
YNAB_PAT
Configuration
Your server can be configured using environment variables. You can place these in a .env file in the project root or set them in your shell.
Variable | Required | Description |
| Yes | Your YNAB Personal Access Token. |
| No | If set, the server operates in single-budget mode, always using this budget ID. The
tool will be hidden. |
| No | Set to
to disable all tools that make changes to your YNAB data. |
Getting Your YNAB Token
Get Your YNAB Token
Go to YNAB Developer Settings
Create a new Personal Access Token
Copy the token value
Set Up Environment
Create a
.envfile in your working directory:YNAB_PAT="your_token_here" YNAB_DEFAULT_BUDGET_ID="your_budget_id" YNAB_READ_ONLY="true"Or set the environment variable directly:
export YNAB_PAT="your_token_here"
Available Tools
The server provides a suite of tools for interacting with your YNAB data. The descriptions explain the purpose and recommended usage for each tool.
Tool | Description |
| Get, update, or refresh a high-level financial overview. This is the best starting point for any analysis , providing account balances, goals, and important context notes. |
| List all accounts for a given budget. Useful for getting account IDs for other tools. |
| Get detailed budget information for a single month, including age of money and total amounts budgeted, spent, and available. Call this to check the monthly budget's status before making changes. |
| List all categories, groups, and their budgeting details. Call this before managing budgeted amounts to see what's available and what's already been allocated. |
| List transactions for a specific account or an entire month. Use this to investigate spending patterns identified in the financial overview. |
| List all upcoming scheduled transactions. Useful for forecasting upcoming bills . |
| Assign a budgeted amount to a category or move money between categories. This is the primary tool for allocating funds . (Write operations disabled in read-only mode) |
| Create, update, or delete multiple transactions at once. More efficient than making single changes. (Write operations disabled in read-only mode) |
| Create, update, or delete a single scheduled (recurring) transaction. Use this to manage recurring bills or savings transfers . (Write operations disabled in read-only mode) |
| List all payees for a given budget. Good for finding payee IDs or identifying messy payee data that needs to be merged. |
| Merge multiple payee names into a single name. Use this to clean up payee data . (Write operations disabled in read-only mode) |
| Look up the name and details of a specific account, category, or payee by its ID. A utility for when you have an ID but need the full context. |
| Look up geographic locations associated with a payee. |
| List all available YNAB budgets (Not available in single-budget mode). |
Development
Local Setup
Clone the repository:
git clone https://github.com/yourusername/ynab-mcp-server.git cd ynab-mcp-serverInstall dependencies:
uv syncRun the server:
uv run ynab-mcp-server
Debugging
Use the MCP Inspector for debugging:
For local development debugging:
You can also view logs with:
Building and Publishing
Contributing
Contributions are welcome! Here's how you can help:
Fork the repository
Create a feature branch (
git checkout -b feature/amazing-feature)Commit your changes (
git commit -m 'Add amazing feature')Push to the branch (
git push origin feature/amazing-feature)Open a Pull Request
Please ensure your PR:
Follows the existing code style
Includes appropriate tests
Updates documentation as needed
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
YNAB API for providing the core functionality
Model Context Protocol for enabling AI assistant integration