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:
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
- Platform-Specific Setup
- Configuration
- Available Tools
- Usage Examples
- Development
- Contributing
- License
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.json
- Windows:
%APPDATA%/Claude/claude_desktop_config.json
- Linux:
~/.config/Claude/claude_desktop_config.json
- MacOS:
- 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-mcp
- Command:
uvx ynab-mcp-server
- Environment Variables:
- YNAB_PAT: your_token_here
- Name:
Other Platforms
For other MCP-compatible platforms, configure using these parameters:
- Server Name:
ynab-mcp
- Command:
uvx
- Arguments:
ynab-mcp-server
- Required 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 |
---|---|---|
YNAB_PAT | Yes | Your YNAB Personal Access Token. |
YNAB_DEFAULT_BUDGET_ID | No | If set, the server operates in single-budget mode, always using this budget ID. The list-budgets tool will be hidden. |
YNAB_READ_ONLY | No | Set to true 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 EnvironmentCreate a
.env
file in your working directory:Or set the environment variable directly:
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 |
---|---|
manage-financial-overview | 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-accounts | List all accounts for a given budget. Useful for getting account IDs for other tools. |
get-month-info | 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-categories | 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 | List transactions for a specific account or an entire month. Use this to investigate spending patterns identified in the financial overview. |
list-scheduled-transactions | List all upcoming scheduled transactions. Useful for forecasting upcoming bills. |
manage-budgeted-amount | 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) |
bulk-manage-transactions | Create, update, or delete multiple transactions at once. More efficient than making single changes. (Write operations disabled in read-only mode) |
manage-scheduled-transaction | 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-payees | List all payees for a given budget. Good for finding payee IDs or identifying messy payee data that needs to be merged. |
manage-payees | Merge multiple payee names into a single name. Use this to clean up payee data. (Write operations disabled in read-only mode) |
lookup-entity-by-id | 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. |
lookup-payee-locations | Look up geographic locations associated with a payee. |
list-budgets | List all available YNAB budgets (Not available in single-budget mode). |
Development
Local Setup
- Clone the repository:
- Install dependencies:
- Run the 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
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.
Tools
An MCP to give AI agents extensive knowledge of your personal finances and control of your budgeting.
- Quick Installation (Claude Desktop)
- Features
- Table of Contents
- Installation & Usage
- Platform-Specific Setup
- Configuration
- Available Tools
- Development
- Contributing
- License
- Acknowledgments
Related Resources
Related MCP Servers
- AsecurityAlicenseAqualityAn MCP server that lets AI assistants interact with your Lunchmoney data, enabling natural language queries about transactions, budgets, and spending patterns.Last updated -438TypeScriptMIT License
- -securityAlicense-qualityAn MCP server that helps AI assistants manage expense-sharing for social events, enabling the creation of gatherings, tracking of expenses, and calculation of fair reimbursements among participants.Last updated -PythonApache 2.0
- -securityFlicense-qualityControl AI agents creation and modification via MCP.Last updated -195JavaScript
- AsecurityFlicenseAqualityAn MCP server that transforms AI assistants into personal chefs by providing recipe recommendations and meal planning features based on the HowToCook repository.Last updated -4337529TypeScript