Skip to main content
Glama

You Need A Budget (YNAB) MCP

by Jtewen

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

Table of Contents

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

  1. 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
  2. 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

  1. Open Goose settings
  2. Navigate to the MCP Servers section
  3. 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.

VariableRequiredDescription
YNAB_PATYesYour YNAB Personal Access Token.
YNAB_DEFAULT_BUDGET_IDNoIf set, the server operates in single-budget mode, always using this budget ID. The list-budgets tool will be hidden.
YNAB_READ_ONLYNoSet to true to disable all tools that make changes to your YNAB data.

Getting Your YNAB Token

  1. Get Your YNAB Token
  2. 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.

ToolDescription
manage-financial-overviewGet, 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-accountsList all accounts for a given budget. Useful for getting account IDs for other tools.
get-month-infoGet 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-categoriesList 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-transactionsList transactions for a specific account or an entire month. Use this to investigate spending patterns identified in the financial overview.
list-scheduled-transactionsList all upcoming scheduled transactions. Useful for forecasting upcoming bills.
manage-budgeted-amountAssign 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-transactionsCreate, update, or delete multiple transactions at once. More efficient than making single changes. (Write operations disabled in read-only mode)
manage-scheduled-transactionCreate, 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-payeesList all payees for a given budget. Good for finding payee IDs or identifying messy payee data that needs to be merged.
manage-payeesMerge multiple payee names into a single name. Use this to clean up payee data. (Write operations disabled in read-only mode)
lookup-entity-by-idLook 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-locationsLook up geographic locations associated with a payee.
list-budgetsList all available YNAB budgets (Not available in single-budget mode).

Development

Local Setup

  1. Clone the repository:
    git clone https://github.com/yourusername/ynab-mcp-server.git cd ynab-mcp-server
  2. Install dependencies:
    uv sync
  3. 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:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. 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

Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

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.

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

  1. Quick Installation (Claude Desktop)
    1. Features
      1. Table of Contents
        1. Installation & Usage
          1. Platform-Specific Setup
            1. Claude Desktop
            2. Goose
            3. Other Platforms
          2. Configuration
            1. Getting Your YNAB Token
          3. Available Tools
            1. Development
              1. Local Setup
              2. Debugging
              3. Building and Publishing
            2. Contributing
              1. License
                1. Acknowledgments

                  Related MCP Servers

                  • 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
                  • -
                    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
                  • 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
                    • Apple

                  View all related MCP servers

                  MCP directory API

                  We provide all the information about MCP servers via our MCP API.

                  curl -X GET 'https://glama.ai/api/mcp/v1/servers/Jtewen/ynab-mcp'

                  If you have feedback or need assistance with the MCP directory API, please join our Discord server