# ynab-mcp

A Model Context Protocol (MCP) server for YNAB (You Need A Budget) that allows Claude to interact with your budgets.

## Features

| Tool                        | Description                                                                   |
| --------------------------- | ----------------------------------------------------------------------------- |
| `list_budgets`              | List all budgets available to your YNAB account                               |
| `list_accounts`             | List all accounts within a specific budget                                    |
| `get_transactions`          | Fetch transactions for an account with optional date filtering                |
| `get_spending_by_category`  | Get aggregated spending totals by category                                    |
| `get_categories`            | Get budget categories with allocated amounts, activity, and remaining balance |
| `get_category_transactions` | Get transactions for a specific category                                      |

## Setup

### 1. Get your YNAB Personal Access Token

1. Go to [YNAB Developer Settings](https://app.ynab.com/settings/developer)
2. Click "New Token" and copy the generated token

### 2. Install dependencies

```bash
bun install
```

### 3. Configure Claude Desktop

Edit your Claude Desktop config file:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Add the YNAB MCP server:

```json
{
  "mcpServers": {
    "ynab": {
      "command": "bun",
      "args": ["/path/to/ynab-mcp/index.ts"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your-personal-access-token-here"
      }
    }
  }
}
```

### 4. Restart Claude Desktop

After saving the config, restart Claude Desktop to load the MCP server.

## Usage

Once configured, you can ask Claude things like:

- "What budgets do I have in YNAB?"
- "Show me my accounts in my main budget"
- "What transactions have I made in my checking account this month?"
- "How much did I spend on groceries last month?"
- "What are my category balances for December?"
- "Show me all restaurant transactions this year"

## Development

Run the server directly for testing:

```bash
YNAB_ACCESS_TOKEN=your-token bun index.ts
```