# ynab-mcp-server

A personal MCP server that gives Claude native access to YNAB budget data.

## Architecture

**Layer 1:** FastMCP reads YNAB's official OpenAPI spec at startup and auto-generates one MCP tool per endpoint.

**Layer 2:** Custom tools for higher-level workflows: spending summaries by category, payee consolidation/renaming.

## Setup

### Prerequisites

- [uv](https://docs.astral.sh/uv/) — Python package manager
- A YNAB Personal Access Token from [app.ynab.com/settings/developer](https://app.ynab.com/settings/developer)

### Install

```bash
uv sync
```

### Configure

Create a `.env` file (never committed):

```
YNAB_API_TOKEN=your_token_here
YNAB_READ_ONLY=false
```

### Run

```bash
YNAB_API_TOKEN=your_token uv run ynab-mcp-server
```

## Connecting to Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ynab": {
      "command": "/absolute/path/to/.venv/bin/ynab-mcp-server",
      "env": {
        "YNAB_API_TOKEN": "your_token_here",
        "YNAB_READ_ONLY": "false"
      }
    }
  }
}
```

Use the absolute path from `which ynab-mcp-server` after `uv sync`.

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `YNAB_API_TOKEN` | Yes | YNAB personal access token |
| `YNAB_READ_ONLY` | No | Set `true` to block all write operations |

## Testing

```bash
npx @modelcontextprotocol/inspector
```