https://github.com/jsclayton/ynab-mcp
YNAB MCP server for Claude — spending analysis, guided reconciliation, and budget management through natural conversation.
https://github.com/jsclayton/ynab-mcp
budgeting claude deno mcp mcp-server personal-fi typescript ynab
Last synced: 2 months ago
JSON representation
YNAB MCP server for Claude — spending analysis, guided reconciliation, and budget management through natural conversation.
- Host: GitHub
- URL: https://github.com/jsclayton/ynab-mcp
- Owner: jsclayton
- License: agpl-3.0
- Created: 2026-03-21T03:20:55.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-31T15:47:29.000Z (2 months ago)
- Last Synced: 2026-03-31T16:06:08.376Z (2 months ago)
- Topics: budgeting, claude, deno, mcp, mcp-server, personal-fi, typescript, ynab
- Language: TypeScript
- Homepage:
- Size: 117 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# ynab-mcp
An MCP server that connects Claude to [YNAB](https://ynab.com) (You Need A
Budget) — enabling financial analysis, guided reconciliation, and budget
management through natural conversation.
## Quick Start
### Prerequisites
- [Deno](https://docs.deno.com/runtime/getting_started/installation/) v2+
- A [YNAB Personal Access Token](https://app.ynab.com/settings/developer)
### Claude Desktop
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"ynab": {
"command": "deno",
"args": ["run", "--allow-net", "--allow-env", "jsr:@jsclayton/ynab-mcp"],
"env": {
"YNAB_ACCESS_TOKEN": "your-token-here"
}
}
}
}
```
Restart Claude Desktop. Ask _"Show me my budget overview"_ to get started.
> **From source:** Replace the JSR specifier with the path to `src/stdio.ts` if running from a local clone.
### Claude Code
```bash
YNAB_ACCESS_TOKEN=your-token-here deno run --allow-net --allow-env jsr:@jsclayton/ynab-mcp
```
### HTTP Server
```bash
YNAB_ACCESS_TOKEN=your-token-here deno run --allow-net --allow-env jsr:@jsclayton/ynab-mcp/http
# → http://localhost:8080/mcp
```
### Docker
```bash
docker run -d \
-e YNAB_ACCESS_TOKEN=your-token-here \
-p 8080:8080 \
ghcr.io/jsclayton/ynab-mcp:latest
# → http://localhost:8080/mcp
```
The image includes a health check on `/health`. All [configuration](#configuration)
is passed via environment variables. To persist the cache across restarts, mount
a volume:
```bash
docker run -d \
-e YNAB_ACCESS_TOKEN=your-token-here \
-e YNAB_CACHE_PATH=/cache \
-v ynab-cache:/cache \
-p 8080:8080 \
ghcr.io/jsclayton/ynab-mcp:latest
```
## What You Can Do
**Analyze spending** — Break down spending by category, track trends over time,
find your top payees, and spot over-budget categories.
**Reconcile accounts** — Walk through uncleared transactions one by one, compare
against your bank balance, and batch-clear confirmed transactions.
**Categorize transactions** — Review uncategorized transactions with
AI-suggested categories based on payee patterns, then batch-update with
approval.
**Manage your budget** — Create transactions, adjust budget amounts, update
goals, rename payees, and manage scheduled transactions.
## Configuration
| Variable | Required | Default | Description |
| ---------------------- | -------- | ------- | ---------------------------------------------------------------- |
| `YNAB_ACCESS_TOKEN` | Yes | — | [Personal access token](https://app.ynab.com/settings/developer) |
| `YNAB_READ_ONLY` | No | `false` | Set to `true` to hide all mutation tools |
| `YNAB_DEFAULT_PLAN_ID` | No | — | Default budget plan ID |
| `YNAB_CACHE_PATH` | No | — | Directory for persistent cache (e.g., `~/.cache/ynab-mcp`) |
| `PORT` | No | `8080` | HTTP server port (HTTP transport only) |
## Documentation
- [Tools Reference](docs/tools.md) — All 7 tools with parameters and examples
- [Resources & Prompts](docs/resources-and-prompts.md) — Lookup resources and
guided workflows
- [Architecture](docs/architecture.md) — How the server is structured
- [Development](docs/development.md) — Running tests, adding tools, contributing
## License
[AGPL-3.0](LICENSE.txt)