YNAB预算管理CLI

ynab-cli

The only YNAB CLI with a built-in MCP server.
Manage your budget from the command line — or let AI agents do it for you.

Features

🤖 AI-Native MCP Server — 37 tools over stdio transport. Works with Claude Desktop, Claude Code, and any MCP-compatible agent. The only YNAB CLI that speaks MCP.

📊 Flexible Output — JSON (default), human-readable tables, or CSV. Pipe to jq, import into spreadsheets, or feed directly to agents.

💵 Dollar Mode — --dollars converts YNAB's milliunits to real currency. No more dividing by 1000 in your head.

🔍 Transaction Search — Find transactions by memo, payee name, or amount range with client-side filtering across your entire history.

📁 Field Filtering & Export — --fields "date,payee_name,amount" keeps output focused. --output report.csv writes directly to file.

⚡ Single Binary — Built in Rust. No runtime, no dependencies, no garbage collector. Starts instantly.

🔐 Secure Auth — Tokens stored in macOS Keychain (with JSON fallback). npm package ships with OIDC provenance attestation.

🔄 Delta Sync — Fetch only what changed since your last request. Efficient polling for automation workflows.

🧩 Full API Coverage — Every YNAB API endpoint has a dedicated command. Anything missing? ynab api GET /plans/... hits the API directly.

Install

npm (easiest)

npm install -g ynab-cli-rs

GitHub Release

# Detect platform and install latest release
curl -sL https://api.github.com/repos/0xdecaf/ynab-cli/releases/latest \
  | grep "browser_download_url.*$(uname -m | sed 's/arm64/aarch64/').*$(uname -s | tr '[:upper:]' '[:lower:]')" \
  | cut -d'"' -f4 | xargs curl -sL | tar xz
sudo mv ynab /usr/local/bin/

Build from source

git clone https://github.com/0xdecaf/ynab-cli.git && cd ynab-cli
cargo build --release
# Binary at target/release/ynab

Quick Start

# 1. Authenticate with your YNAB personal access token
ynab auth login --pat

# 2. See your budgets
ynab plans list

# 3. Set a default so you never need --plan-id again
ynab plans set-default <PLAN_ID>

# 4. You're in
ynab accounts list --dollars
ynab transactions list --since-date 2026-01-01 --dollars

Get a personal access token at app.ynab.com/settings/developer

Usage

Every resource has its own subcommand. Here are the highlights — run ynab <command> --help for full details.

Transactions

ynab transactions list                                    # all transactions
ynab transactions list --type uncategorized               # find uncategorized
ynab transactions search --payee-name "Starbucks"         # search by payee
ynab transactions search --memo "coffee" --dollars        # search by memo
ynab transactions create --json '{"account_id":"...","date":"2026-03-10","amount":-25000,"payee_name":"Coffee Shop"}'
ynab transactions update --transaction-id <ID> --json '{"memo":"Updated"}'
ynab transactions update-bulk --json '[{"id":"...","approved":true}]'

Budget & Categories

ynab categories list                                      # all categories
ynab categories budget --month 2026-03-01 --category-id <ID> --budgeted 500000
ynab categories update --category-id <ID> --json '{"name":"Dining Out"}'
ynab months get --month 2026-03-01 --dollars              # monthly breakdown

Accounts & Payees

ynab accounts list --dollars --fields "name,type,balance" # quick balance check
ynab accounts create --json '{"name":"Savings","type":"savings","balance":0}'
ynab payees update --payee-id <ID> --json '{"name":"New Name"}'

Scheduled Transactions

ynab scheduled list                                       # all recurring
ynab scheduled delete --scheduled-transaction-id <ID>     # remove one

Raw API Access

ynab api GET /plans
ynab api PATCH /plans/<ID>/categories/<ID> --body '{"category":{"name":"X"}}'

The /v1 prefix is optional; paths are relative to the API root.

Output Options

ynab transactions list --output-format table              # human-readable
ynab transactions list --output-format csv --output spending.csv  # export
ynab transactions list --dollars --fields "date,payee_name,amount"  # focused
ynab transactions list --dry-run                          # preview HTTP request

MCP Server

Start the server:

ynab mcp

37 tools — one per API endpoint — over stdio transport. Every tool accepts plan_id as the first parameter and returns JSON.

Claude Desktop

{
  "mcpServers": {
    "ynab": {
      "command": "ynab",
      "args": ["mcp"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Claude Code

{
  "mcpServers": {
    "ynab": {
      "command": "ynab",
      "args": ["mcp"],
      "env": {
        "YNAB_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Read-only mode

To let an agent inspect a budget without being able to change it, start the server with ynab mcp --read-only (or set YNAB_MCP_READ_ONLY=1 in the MCP config's env). Every create, update, delete, import, and budget-assignment tool then returns an error instead of calling the API. See SECURITY.md for the full threat model.

What agents can do

• "How much did I spend on dining this month?"
• "Approve all uncategorized transactions as groceries"
• "Budget $200 for entertainment next month"
• "Export this month's spending to CSV"
• "What's my account balance across all accounts?"

The MCP server gives agents full read/write access to your YNAB data through structured tool calls.

Agent skills

SKILL.md and the skills/ directory are instruction files for coding agents (Claude Code and compatible tools) that describe how to drive ynab-cli well. They are not required to use the CLI.

Global Flags

Authentication

Token resolution order:

1. --token <TOKEN> flag (highest priority)
2. YNAB_ACCESS_TOKEN environment variable
3. OS keychain entry saved by ynab auth login
4. The ynab-cli credentials file in the platform config directory (~/.config/ynab/ on Linux, ~/Library/Application Support/ynab/ on macOS), mode 0600

Contributing

git clone https://github.com/0xdecaf/ynab-cli.git
cd ynab-cli
cargo build
cargo test --all
cargo clippy --all-targets --all-features

PRs welcome. Please run cargo fmt --all before submitting.

License

MIT