ynab-mcp-server

roeeyn/ynab-mcp-server

3.2

If you are the rightful owner of ynab-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

YNAB MCP Server is a Model Context Protocol server designed for seamless integration with the YNAB API, allowing AI assistants to interact with YNAB budgets, accounts, and transactions.

Tools
5
Resources
0
Prompts
0

YNAB MCP Server

License: MIT

Model Context Protocol (MCP) server for YNAB (You Need A Budget) API integration. This server enables AI assistants like Claude to interact with your YNAB budgets, accounts, transactions, and more.

Features

  • Secure authentication using YNAB Personal Access Tokens
  • Full access to YNAB API endpoints via OpenAPI spec
  • Built with FastMCP for seamless MCP integration
  • Includes unit tests for core functionality
  • Easy installation with uv

Prerequisites

  • Python 3.13 or higher
  • uv package manager
  • A YNAB account and Personal Access Token

Getting a YNAB Personal Access Token

  1. Log in to your YNAB account
  2. Go to Account Settings (click your email in the bottom left)
  3. Navigate to the Developer Settings section
  4. Click New Token
  5. Enter a name for your token (e.g., "MCP Server")
  6. Click Generate and copy the token
  7. Important: Save this token securely - you won't be able to see it again!

Finding Your Budget ID

Your Budget ID can be found in the URL when viewing your budget in YNAB:

https://app.ynab.com/<YOUR_BUDGET_ID>/budget

Alternatively, you can use the YNAB API to list all your budgets and find the ID you need.

Installation

From Source

  1. Clone the repository:
git clone https://github.com/yourusername/ynab-mcp-server.git
cd ynab-mcp-server
  1. Install dependencies using uv:
uv sync
  1. (Optional) Run tests:
uv run pytest

Usage

Claude Desktop

To use this MCP server with Claude Desktop, add the following configuration to your Claude Desktop config file:

Location of config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "ynab": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/ynab-mcp-server",
        "run",
        "ynab-mcp-server"
      ],
      "env": {
        "YNAB_API_TOKEN": "your-ynab-personal-access-token",
        "YNAB_BUDGET_ID": "your-budget-id-optional"
      }
    }
  }
}

Replace:

  • /ABSOLUTE/PATH/TO/ynab-mcp-server with the actual path to this repository
  • your-ynab-personal-access-token with your YNAB Personal Access Token
  • your-budget-id-optional with your YNAB Budget ID (this is optional but recommended)

After updating the config, restart Claude Desktop.

Cline (VS Code Extension)

Add this to your Cline MCP settings:

{
  "mcpServers": {
    "ynab": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/ynab-mcp-server",
        "run",
        "ynab-mcp-server"
      ],
      "env": {
        "YNAB_API_TOKEN": "your-ynab-personal-access-token",
        "YNAB_BUDGET_ID": "your-budget-id-optional"
      }
    }
  }
}

Continue (VS Code Extension)

In your Continue configuration (~/.continue/config.json):

{
  "mcpServers": [
    {
      "name": "ynab",
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/ynab-mcp-server",
        "run",
        "ynab-mcp-server"
      ],
      "env": {
        "YNAB_API_TOKEN": "your-ynab-personal-access-token",
        "YNAB_BUDGET_ID": "your-budget-id-optional"
      }
    }
  ]
}

Zed Editor

Add to your Zed settings:

{
  "context_servers": {
    "ynab": {
      "command": {
        "path": "uv",
        "args": [
          "--directory",
          "/ABSOLUTE/PATH/TO/ynab-mcp-server",
          "run",
          "ynab-mcp-server"
        ],
        "env": {
          "YNAB_API_TOKEN": "your-ynab-personal-access-token",
          "YNAB_BUDGET_ID": "your-budget-id-optional"
        }
      }
    }
  }
}

Other MCP Clients

For other MCP clients, use the following command:

YNAB_API_TOKEN=your-token YNAB_BUDGET_ID=your-budget-id uv run ynab-mcp-server

Available Tools

This MCP server exposes all YNAB API endpoints as tools. Some of the most useful ones include:

  • Budgets: List and retrieve budget information
  • Accounts: Get account balances and details
  • Transactions: Create, update, and query transactions
  • Categories: Manage budget categories
  • Payees: List and manage payees
  • Scheduled Transactions: View and manage scheduled transactions
  • Months: Get budget data for specific months

For a complete list of available endpoints, refer to the YNAB API Documentation.

Example Prompts

Once configured, you can ask Claude questions like:

  • "What's my current checking account balance in YNAB?"
  • "Show me all transactions from last month"
  • "Create a new transaction for $50 at Starbucks in my Coffee category"
  • "What are my budget categories and their available amounts?"
  • "Show me my upcoming scheduled transactions"

Development

Running Tests

uv run pytest

Running Pre-commit Hooks

# Install pre-commit hooks
uv run pre-commit install

# Run manually on all files
uv run pre-commit run --all-files

Running the Server Locally

YNAB_API_TOKEN=your-token uv run ynab-mcp-server

Security Considerations

  • Never commit your YNAB Personal Access Token to version control
  • Store your token securely in environment variables or a secure credential manager
  • The token provides full access to your YNAB account, treat it like a password
  • Consider using a dedicated YNAB budget for testing if you're concerned about security

Troubleshooting

Server not connecting

  • Verify your YNAB_API_TOKEN is correct and hasn't expired
  • Check that the path to the repository is absolute, not relative
  • Ensure uv is installed and available in your PATH

API errors

  • Ensure you have an active YNAB subscription
  • Verify your token has not been revoked
  • Check the YNAB API status at https://status.ynab.com/

Token expired or invalid

  • Generate a new Personal Access Token in YNAB Account Settings
  • Update your configuration with the new token
  • Restart your MCP client

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

  • YNAB for providing an excellent budgeting tool and API
  • FastMCP for making MCP server development simple
  • Anthropic for Claude and the Model Context Protocol

Related Projects

Support

If you encounter any issues or have questions:

  1. Check the Troubleshooting section
  2. Review existing GitHub Issues
  3. Create a new issue with details about your problem

Made with care for the YNAB and MCP communities