ynab-mcp
An MCP (Model Context Protocol) server that exposes YNAB (You Need A Budget) data to AI assistants like Claude.
Prerequisites
- asdf with the
nodejsplugin installed - A YNAB Personal Access Token (create one here)
Setup```bash
Install the pinned Node.js version
asdf install
Install dependencies
npm install
Configure your YNAB token
cp .env.example .env
Edit .env and add your YNAB_API_TOKEN
## Development```bash
# Run in dev mode (no build step)
npm run dev
# Type check
npm run typecheck
# Build
npm run build
# Run the built server
npm start
Testing with MCP Inspector
The MCP Inspector lets you interactively call tools in a browser UI:```bash
Dev mode (no build needed)
YNAB_API_TOKEN=your_token npx @modelcontextprotocol/inspector tsx src/index.ts
Or from built output
npm run build
YNAB_API_TOKEN=your_token npx @modelcontextprotocol/inspector node dist/index.js
## Claude Desktop Configuration
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:```json
{
"mcpServers": {
"ynab": {
"command": "node",
"args": ["/absolute/path/to/ynab-mcp/dist/index.js"],
"env": {
"YNAB_API_TOKEN": "your_token_here"
}
}
}
}
Available Tools
| Tool | Description |
|---|---|
get_budgets |
List all budgets |
get_budget |
Get detailed budget info (accounts, categories, payees) |
get_accounts |
List all accounts in a budget |
get_categories |
List all category groups and categories |
get_transactions |
List transactions with optional date/type filters |
create_transaction |
Create a new transaction |
update_transaction |
Update an existing transaction |
get_payees |
List all payees |
get_months |
List all budget months |
get_month_by_id |
Get a single month with category-level detail |
Note on amounts
YNAB uses milliunits for all amounts: 1 USD = 1000 milliunits. When creating or updating transactions, use negative values for outflows (spending) and positive values for inflows (income). For example, a $25.50 purchase is -25500.
License
MIT
