npm package: @smurmann/ynab-mcp
Description: MCP server for YNAB — lets Claude help you manage your budget
Latest version: 1.0.0

# ynab-mcp

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that connects Claude to your [YNAB](https://www.ynab.com/) budget. Ask Claude questions about your finances, log transactions, adjust your budget, and more — all in natural language.

Each user runs their own instance with their own YNAB token. Your financial data never leaves your machine.

## What you can do

- **Check balances** — "What's my checking account balance?"
- **Review your budget** — "How much do I have left in Groceries this month?"
- **See spending** — "What did I spend on restaurants in March?"
- **Log transactions** — "Add a $45 lunch at Chipotle to my Dining Out category"
- **Approve imports** — "Show me my unapproved transactions and approve them all"
- **Manage recurring bills** — "What bills are coming up this month?"
- **Adjust budget amounts** — "Move $100 more into my Car Maintenance envelope"

## Prerequisites

- [Node.js](https://nodejs.org/) 18 or later
- A [YNAB account](https://www.ynab.com/)
- A YNAB Personal Access Token (free, see below)

## Getting a YNAB Token

1. Log in to YNAB
2. Go to **Account Settings → Developer Settings**
3. Click **New Token**, give it a name, and copy the token

## Installation

### Option A: npx (no install required)

```json
{
  "mcpServers": {
    "ynab": {
      "command": "npx",
      "args": ["-y", "ynab-mcp"],
      "env": {
        "YNAB_TOKEN": "your-token-here"
      }
    }
  }
}
```

### Option B: Global install

```bash
npm install -g ynab-mcp
```

```json
{
  "mcpServers": {
    "ynab": {
      "command": "ynab-mcp",
      "env": {
        "YNAB_TOKEN": "your-token-here"
      }
    }
  }
}
```

## Claude Code setup

Run this command to add the MCP server:

```bash
claude mcp add ynab -e YNAB_TOKEN=your-token-here -- npx -y ynab-mcp
```

Or add it manually via **Claude Code → Settings → MCP Servers**.

Then restart Claude Code and ask something like: *"What's my budget status this month?"*

### Optional: set a default budget

If you have multiple YNAB budgets, you can pin one so you don't need to specify it every time. Add `YNAB_BUDGET_ID` alongside your token:

```bash
claude mcp add ynab -e YNAB_TOKEN=your-token-here -e YNAB_BUDGET_ID=your-budget-id -- npx -y ynab-mcp
```

Run `list_budgets` in Claude to find your budget ID.

## Available tools

| Tool | Description |
|------|-------------|
| `list_budgets` | List all your YNAB budgets |
| `list_accounts` | List accounts with current balances |
| `list_categories` | List all budget categories with assigned/spent/available amounts |
| `get_category_for_month` | Get a category's amounts for a specific month |
| `update_category_budget` | Change how much is assigned to a category |
| `get_budget_month` | Monthly summary: income, spending, Ready to Assign, Age of Money |
| `list_budget_months` | All months with summary totals |
| `list_transactions` | List transactions, filterable by account/category/payee/date/status |
| `create_transaction` | Log a new transaction |
| `update_transaction` | Edit an existing transaction |
| `approve_transactions` | Bulk-approve multiple transactions |
| `list_scheduled_transactions` | List upcoming recurring transactions |
| `create_scheduled_transaction` | Set up a new recurring transaction |
| `list_payees` | List all payees |

## Rate limits

YNAB allows 200 API requests per hour per token. Normal conversational use stays well within this limit.

## License

MIT