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"
}

Related MCP server: Personal Finance AI MCP

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:

# 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.

Getting Your YNAB Token

1. Get Your YNAB Token

   • Go to YNAB Developer Settings

   • Create a new Personal Access Token

   • Copy the token value

2. Set Up Environment

   Create 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.

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

• YNAB API for providing the core functionality

• Model Context Protocol for enabling AI assistant integration