Skip to main content
Glama
YNAB Local MCP

YNAB Local MCP

by ctcampbell

YNAB Local MCP

Connect your YNAB budget to an AI assistant through the Model Context Protocol (MCP). Run the server on your computer, home server, or NAS, then connect an MCP client to review accounts, categories, transactions, and upcoming bills.

  • Read-only by default, with 13 tools for exploring your budget.

  • Optional edits to create transactions, update transactions, and set monthly category assignments. Each edit starts with a preview.

  • Self-hosted, with Docker Compose and a local desktop bridge included.

This is an independent project, not an official YNAB product. Each server connects to one owner's YNAB account. It does not need an OpenAI API key unless you choose the optional ChatGPT tunnel.

Quick start with Docker

You need a YNAB account, Docker with Compose v2 or later, and outbound internet access. The shell commands below work on macOS, Linux, or WSL.

1. Get the source and create the configuration

Clone this repository using the URL from GitHub's Code button, or choose Download ZIP and extract it. Open a terminal in the folder containing compose.yaml.

If you have Node.js 24 or later:

node scripts/setup.mjs

Otherwise, run setup through Docker:

docker run --rm --user "$(id -u):$(id -g)"   -v "$PWD:/work" -w /work node:24-bookworm-slim node scripts/setup.mjs

Setup creates .env for settings and .secrets/ for credentials. It preserves existing files, so you can run it again safely.

2. Add your YNAB token

In the YNAB web app, open Account Settings → Developer Settings → Personal Access Tokens and create a token. Open .secrets/ynab-token in a local text editor and replace the placeholder with only the token. Save the file. See YNAB's token guide if you need help finding it.

Keep .secrets/ and .env private. They are excluded from Git and the generated source archive. Your desktop client uses the separate, generated mcp-authorization file; it does not need your YNAB token.

3. Start the server

docker compose up -d --build
docker compose ps
curl --fail http://127.0.0.1:3000/healthz

The health check should return:

{"status":"ok","service":"ynab-local-mcp"}

This confirms the server is running. The first YNAB tool call in the next step confirms that your token works. Port 3000 is available only on the host computer.

4. Connect your assistant

Choose the guide for your client:

Client

Setup

Local MCP client or desktop app

Connect a local client

ChatGPT on the web

Connect through a private tunnel

Once connected, ask: “List my YNAB budgets and their currencies.” This calls ynab_list_plans without changing anything. YNAB calls budgets plans in its API.

Then try “Review this month's overspending” or “Show my upcoming transactions.”

Related MCP server: YNAB MCP Server

Enable edits (optional)

Set YNAB_ENABLE_WRITES=true in .env, then recreate the server:

docker compose up -d --force-recreate ynab-mcp

Reconnect your client or refresh its tools. Edits default to previews; saving requires dry_run=false. Review the proposed changes before approving them in your client. See the tool guide for supported edits and limits.

To turn edits off, set the value back to false and recreate the server again.

Privacy

Anyone with access to this server can read the connected account's allowed plans and, if enabled, edit them. Use it for your own account, not as a shared service for unrelated users. Tool results are sent to the assistant you connect.

The server keeps a short-lived memory cache, has no database, and does not log request bodies. Keep the default loopback binding; use an SSH forward or the private tunnel for remote access. See networking and privacy.

More help

License

Project code is MIT licensed. Bundled schemas retain their upstream license.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Connects AI assistants to YNAB budgets, providing over 30 tools for managing budgets, accounts, transactions, categories, and analytics with delta sync and caching.
      47
      49
      AGPL 3.0
    • A
      license
      B
      quality
      A
      maintenance
      Enables AI assistants to interact with YNAB budgets, performing read-only queries by default and optional write operations like creating transactions and managing categories through natural language.
      45
      743 npm
      52
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Provides a read-only interface to YNAB budget data, allowing AI assistants to inspect budgets, accounts, categories, transactions, and more. Includes an experimental guarded write workflow for category assignments.
      10
      12 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to connect to YNAB budgets, providing tools for accounts, transactions, categories, payees, and analytics, including search, bulk operations, and delta sync.
      47
      AGPL 3.0