You Need A Budget (YNAB) MCP

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)

{
  "mcpServers": {
    "ynab-mcp": {
      "command": "uvx",
      "args": ["ynab-mcp-server"],
      "env": {
        "YNAB_PAT": "your_token_here",
      }
    }
  }
}

Optional environment variables:

"env": {
  "YNAB_DEFAULT_BUDGET_ID": "your_budget_id",
  "YNAB_READ_ONLY": "true"
}

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

Installation & Usage

No installation needed when using uvx:

# Run directly (recommended)
uvx ynab-mcp-server

# Or with specific version
uvx ynab-mcp-server@0.1.1

For development:

# Clone and run from source
git clone https://github.com/yourusername/ynab-mcp-server.git
cd ynab-mcp-server
uv run ynab-mcp-server

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
Add the YNAB MCP server configuration:

{
  "mcpServers": {
    "ynab-mcp": {
      "command": "uvx",
      "args": ["ynab-mcp-server"],
      "env": {
        "YNAB_PAT": "your_token_here"
      }
    }
  }
}

Optional environment variables:

env: {
  "YNAB_DEFAULT_BUDGET_ID": "your_budget_id",
  "YNAB_READ_ONLY": "true"
}

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

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:
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
`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:
git clone https://github.com/yourusername/ynab-mcp-server.git cd ynab-mcp-server
Install dependencies:
uv sync
Run the server:
uv run ynab-mcp-server

Debugging

Use the MCP Inspector for debugging:

npx @modelcontextprotocol/inspector uvx ynab-mcp-server

For local development debugging:

cd path/to/ynab-mcp-server
npx @modelcontextprotocol/inspector uv run ynab-mcp-server

You can also view logs with:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Building and Publishing

# Build package
uv build

# Publish to PyPI
uv publish

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

Install Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

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

View all tools

An MCP to give AI agents extensive knowledge of your personal finances and control of your budgeting.

Related Resources

Reddit Discussion about this server

Related MCP Servers

lunchmoney-mcp
leafeye
A
security
A
license
A
quality
An MCP server that lets AI assistants interact with your Lunchmoney data, enabling natural language queries about transactions, budgets, and spending patterns.
Last updated -
4
3
8
TypeScript
MIT License
Gatherings MCP Server
abutbul
-
security
A
license
-
quality
An 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 -
Python
Apache 2.0
Letta Agents MCP Server
elijahdev0
-
security
F
license
-
quality
Control AI agents creation and modification via MCP.
Last updated -
195
JavaScript
HowToCook-MCP Server
worryzyy
A
security
F
license
A
quality
An MCP server that transforms AI assistants into personal chefs by providing recipe recommendations and meal planning features based on the HowToCook repository.
Last updated -
4
337
529
TypeScript

View all related MCP servers