nkcmr/ynab-mcp

Watch 1

Star 0

Fork

You've already forked ynab-mcp

0

An MCP server for YNAB (https://www.ynab.com/), exposing 20 tools for querying and managing your budget through any MCP-compatible client (Claude Desktop, etc.).

ai mcp-server ynab ynab-api

32 commits1 branch6 tags 6.6 MiB

• Go 99.9%
• Dockerfile 0.1%

Find a file

HTTPS

nick comer 8e03f96348 feat: exclude transfers from uncategorized transaction listings by default ...When type=uncategorized, transfer transactions are now filtered out of results unless include_transfers=true is explicitly set. This avoids surfacing transfers (which are inherently uncategorized) when the intent is to find transactions that need categorization.	2026-03-23 23:11:46 +00:00
cmd/ynab-mcp	refactor: migrate CLI flags to cobra with stdio/http subcommands	2026-03-21 13:55:59 +00:00
docs/superpowers	feat: add ynab_transactions_batch_update MCP tool	2026-03-22 12:50:51 +00:00
internal	feat: exclude transfers from uncategorized transaction listings by default	2026-03-23 23:11:46 +00:00
.gitignore	chore: ignore vendor directory	2026-03-21 23:05:35 +00:00
Dockerfile	feat: add CLI entry point and Dockerfile	2026-03-21 13:39:26 +00:00
go.mod	refactor: migrate CLI flags to cobra with stdio/http subcommands	2026-03-21 13:55:59 +00:00
go.sum	refactor: migrate CLI flags to cobra with stdio/http subcommands	2026-03-21 13:55:59 +00:00
mise.toml	chore: add release task to mise.toml with datever versioning and opencode release notes	2026-03-21 13:49:58 +00:00
oapi-codegen.yaml	feat: scaffold project with oapi-codegen and generated YNAB client	2026-03-21 12:45:33 +00:00
README.md	docs: update README to reflect recent changes	2026-03-23 09:15:33 +00:00
ynab-api-3.0.yaml	fix: handle HTTP 200 response from batch update transactions endpoint	2026-03-22 13:07:31 +00:00
ynab-api.yaml	fix: handle HTTP 200 response from batch update transactions endpoint	2026-03-22 13:07:31 +00:00

README.md

ynab-mcp

An MCP server for YNAB (You Need a Budget), exposing 21 tools for querying and managing your budget through any MCP-compatible client (Claude Desktop, etc.).

Tools

Tool	Description
ynab_user_get	Get authenticated user info
ynab_plans_list	List all plans (budgets)
ynab_plan_get	Get a single plan
ynab_plan_settings_get	Get plan settings (currency/date format)
ynab_accounts_list	List accounts in a plan
ynab_account_get	Get a single account
ynab_categories_list	List all category groups and categories
ynab_category_get	Get a single category
ynab_month_category_get	Get category budget data for a specific month
ynab_payees_list	List all payees
ynab_payee_get	Get a single payee
ynab_months_list	List all budget months
ynab_month_get	Get budget details for a specific month
ynab_transactions_list	List transactions with optional filtering
ynab_transaction_get	Get a single transaction
ynab_transaction_create	Create a new transaction
ynab_transaction_update	Update an existing transaction (partial)
ynab_transaction_delete	Delete a transaction
ynab_transactions_batch_update	Update multiple transactions in a single call
ynab_scheduled_transactions_list	List scheduled transactions
ynab_scheduled_transaction_get	Get a single scheduled transaction

Monetary amounts are in YNAB's milliunit format: 1000 milliunits = $1.00.

Prerequisites

• A YNAB personal access token
• Go 1.25+ (to build from source) or Docker

Installation

From source:

go install code.nkcmr.net/ynab-mcp/cmd/ynab-mcp@latest

Build locally:

git clone https://github.com/nkcmr/ynab-mcp
cd ynab-mcp
go build ./cmd/ynab-mcp

Docker:

docker build -t ynab-mcp .

Configuration

The binary uses subcommands to select the transport: ynab-mcp stdio or ynab-mcp http. Most flags accept an environment variable fallback.

Global flags (available to all subcommands):

Flag	Env Var	Required	Default	Description
--token	YNAB_API_TOKEN	Yes	—	YNAB personal access token, or a path to a file containing the token
--plan	YNAB_DEFAULT_PLAN	No	last-used	Default plan (budget) ID. Omit to use your most recently accessed plan

http subcommand flags:

Flag	Env Var	Required	Default	Description
--addr	—	No	:8080	Listen address
--cf-access-team	CF_ACCESS_TEAM	Yes	—	Cloudflare Access team name
--cf-access-aud	CF_ACCESS_AUD	Yes	—	Cloudflare Access application AUD tag

The --token flag accepts either a literal token string or a filesystem path. If the value is a readable file, the token is read from it (whitespace trimmed).

Usage

Claude Desktop (stdio)

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ynab": {
      "command": "/path/to/ynab-mcp",
      "args": ["--token", "/path/to/token-file", "stdio"]
    }
  }
}

Or with the token inline:

{
  "mcpServers": {
    "ynab": {
      "command": "/path/to/ynab-mcp",
      "args": ["stdio"],
      "env": {
        "YNAB_API_TOKEN": "your-token-here"
      }
    }
  }
}

HTTP transport (remote access)

The HTTP transport uses Cloudflare Access for authentication. Every request must carry a valid Cloudflare Access JWT.

ynab-mcp \
  --token /run/secrets/ynab-token \
  http \
  --addr :8080 \
  --cf-access-team myteam \
  --cf-access-aud your-aud-tag

Or with Docker:

docker run \
  -e YNAB_API_TOKEN=your-token \
  -e CF_ACCESS_TEAM=myteam \
  -e CF_ACCESS_AUD=your-aud-tag \
  -p 8080:8080 \
  ynab-mcp http

Development

# Run tests
go test ./...

# Regenerate the YNAB API client (after updating ynab-api.yaml)
go generate ./internal/ynab/...

# Build
go build ./cmd/ynab-mcp

The YNAB API client is generated from ynab-api.yaml using oapi-codegen. The generated file (internal/ynab/client.gen.go) is committed — regenerate it only when the spec changes.