# mcp-ynab

A [Model Context Protocol](https://modelcontextprotocol.io) server for the
[YNAB](https://www.ynab.com) (You Need A Budget) API. Lets MCP clients (Claude
Desktop, Claude Code, custom agents) read your budgets, accounts, and
transactions, and create or recategorize transactions through structured tools.

## Install

The project is managed with [uv](https://docs.astral.sh/uv/) and
[Task](https://taskfile.dev/). All Python commands in this repo go through
`uv run`.

```bash
uv sync                  # install dependencies
task install             # install the mcp-ynab CLI into the venv
```

## Configure

Set your YNAB Personal Access Token in the environment (or in a `.env` file at
the repo root):

```bash
export YNAB_API_KEY=your-personal-access-token
```

Get a token at <https://app.ynab.com/settings/developer>.

## Quickstart

### 1. Set your API key
Code Mode is the default surface — it requires your YNAB API key:
```bash
export YNAB_API_KEY="your-key-here"
```
Or store it in your OS keychain (the server reads it automatically).

### 2. Use Code Mode
By default the server exposes two tools: **`search`** (discover available operations) and **`execute`** (run a snippet against the live YNAB API).

**Discover tools:**
```python
# In the search tool:
return [t for t in spec if "transaction" in t["name"]]
```

**Execute a query:**
```python
# In the execute tool:
return await ynab.read.get_budgets()
```

### 3. Restore the full tool surface (optional)
To access all ~34 direct YNAB tools, set the escape-hatch preference:
```text
set_preference: code_mode_replace_tools = false
```

## Run the server

```bash
mcp-ynab                 # production
task dev                 # dev mode + MCP Inspector in the browser
```

## Tools and resources

By default, the public MCP tool surface is intentionally small:

| Tool | Purpose |
| ---- | ------- |
| `search` | Discover available YNAB operations without live API access |
| `execute` | Run a short Python snippet against the live YNAB API |
| `ping` | Health check the server |
| `get_preferences` | Inspect server preferences |
| `set_preference` | Update preferences such as mutation or escape-hatch settings |
| `set_api_key` | Store a YNAB API key in the OS keychain |
| `clear_api_key` | Remove the stored YNAB API key |
| `set_preferred_budget_id` | Cache a preferred budget ID for default-targeted calls |

Use `search` to discover operations:

```python
return [
    {"name": tool["name"], "description": tool["description"]}
    for tool in spec
    if "category" in tool["name"]
]
```

Then call the operation through `execute`:

```python
categories = await ynab.read.get_categories()
return [
    {"name": category.name, "balance": category.balance}
    for group in categories
    for category in group.categories[:LIMIT]
]
```

Mutating operations live under `ynab.write.*` and require
`code_mode_mutations_enabled=true`:

```python
result = await ynab.write.bulk_categorize(assignments=assignments)
return result
```

The underlying direct tools still exist in the internal FastMCP registry so
Code Mode can dispatch through `ynab.read.*`, generate stubs, and build the
search catalog. They are hidden from the public tool list by default. Set
`code_mode_replace_tools=false` to restore the full direct-tool surface as an
escape hatch.

Representative internal direct tools include:

**Read-only internal tools**

| Tool | Purpose |
| ---- | ------- |
| `get_budgets` | List all budgets in markdown |
| `get_accounts` | List accounts in a budget, grouped by type with summary |
| `get_account_balance` | Return a single account's current balance in dollars |
| `get_transactions` | Recent transactions for an account; optional `since_date` |
| `get_transactions_needing_attention` | Filter for uncategorized / unapproved transactions |
| `get_categories` | All categories in a budget grouped by category group |

**Mutating internal tools**

| Tool | Purpose |
| ---- | ------- |
| `create_transaction` | Create a new transaction in YNAB |
| `categorize_transaction` | Assign a category to an existing transaction |
| `set_preferred_budget_id` | Cache a preferred budget ID for default-targeted tools |
| `cache_categories` | Cache a budget's category list locally |

For account transfers and credit-card payments, use the destination account's
transfer payee ID as `payee_id` when creating or updating a transaction. The
`get_payees` tool lists transfer payees with their `Transfer Account ID`.
Do not pass a `Transfer : ...` value as `payee_name`; YNAB rejects or treats
that as a regular payee instead of creating a linked transfer.

**Resources**

- `ynab://preferences/budget_id` — currently preferred budget ID
- `ynab://categories/{budget_id}` — cached categories for a budget
- `ynab://code-mode/stubs` — generated Python stubs for Code Mode
- `ynab://code-mode/examples` — curated Code Mode snippets

## Code Mode

Code Mode exposes `execute`, a Python execution tool for multi-step YNAB
workflows. It is enabled by default and controlled through the preferences
`code_mode_enabled`, `code_mode_mutations_enabled`, and `code_mode_replace_tools`.

See [src/mcp_ynab/code_mode/README.md](src/mcp_ynab/code_mode/README.md)
for usage, wiring instructions, and runner limits.

## Development

```bash
task fmt                 # ruff format + check --fix
task lint                # ruff check + format --check (no auto-fix)
task typecheck           # mypy
task docstrings          # interrogate (fails under 80%)
task test                # unit tests only (default; integration excluded)
task coverage            # unit tests with coverage report
```

## Integration tests

Integration tests are gated behind `pytest.mark.integration` and excluded from
the default `task test` run. They make real calls to your YNAB account, so they
require `YNAB_API_KEY`.

```bash
YNAB_API_KEY=your-token task test:integration
```

The default integration suite is **read-only**. Tests that mutate data
(create_transaction, categorize_transaction) require an additional opt-in:

```bash
YNAB_API_KEY=your-token YNAB_INTEGRATION_ALLOW_WRITES=1 \
  task test:integration
```

## License

MIT