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

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

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

YNAB MCP Server

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

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

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

You Need A Budget (YNAB) MCP

YNAB MCP Server

Quick Installation (Claude Desktop)

Features

Table of Contents

Installation & Usage

Platform-Specific Setup

Claude Desktop

Goose

Other Platforms

Configuration

Getting Your YNAB Token

Available Tools

Development

Local Setup

Debugging

Building and Publishing

Contributing

License

Acknowledgments

YNAB MCP Server

Quick Installation (Claude Desktop)

Features

Table of Contents

Installation & Usage

Platform-Specific Setup

Claude Desktop

Goose

Other Platforms

Configuration

Getting Your YNAB Token

Available Tools

Development

Local Setup

Debugging

Building and Publishing

Contributing

License

Acknowledgments