YNAB MCP

MCP Server for YNAB

Turn natural-language budget questions into safe, local YNAB API workflows
Give your AI assistant read-only budget access by default, with explicit write opt-in

47 tools with writes enabled • YNAB API v1.85 • read-only by default

Quick Start • Plugin • Claude Code • Codex • Other Hosts • What You Can Do • Tools Reference • Configuration

---

Run YNAB through Claude Code, Codex, Hermes, Antigravity, or any stdio MCP host without a marketplace plugin. This server gives AI assistants a local, rate-aware YNAB API layer that is read-only by default, speaks in dollars instead of milliunits, and exposes write tools only after explicit opt-in.

Why This Exists

YNAB's budgeting philosophy works best when you interact with your budget frequently, but the app interface is not designed for quick questions or careful bulk cleanup. "How much did I spend on groceries this month?" should not require navigating three screens. "Categorize all my Amazon orders from this week" should not become a manual, one-by-one review.

This server gives your AI assistant a safe local interface to YNAB's API, turning natural language into structured budget review and, when explicitly enabled, budget operations. It is designed for real budgeting work: finding overspending, reviewing unapproved transactions, checking category drift, investigating recurring payments, and making verified batch updates without giving the assistant broader access than it needs.

All monetary values are automatically converted between dollars and YNAB's internal milliunits format so the AI never has to think about it. The server uses the official YNAB JavaScript SDK where it fits, plus direct API calls for newer endpoints and query parameters that the SDK has not caught up with yet.

---

Quick Start

This package stands on its own as a stdio MCP server. You can install it from this repo as a standalone Claude Code, Codex, Hermes, or Antigravity plugin, or register the npm package directly and let your MCP client launch it on demand. You do not need the older ames-connectors marketplace for YNAB.

This is the local, owner-run package. It uses a personal access token because it is intended for a YNAB account owner running the MCP server for that same account. A public connector for other YNAB users should be reviewed as an OAuth application and should follow the hosted pattern in docs/hosted-oauth-connector.md.

Install as a Plugin

Install the standalone marketplace from this repository:

/plugin marketplace add oliverames/ynab-mcp-server
/plugin install ynab-mcp-server@ynab-mcp-server

Install the same marketplace in Codex:

codex plugin marketplace add oliverames/ynab-mcp-server
codex plugin add ynab-mcp-server@ynab-mcp-server

The plugin starts @oliverames/mcp-server-for-ynab@latest and preserves the prior ames-ynab connector behavior by setting YNAB_ALLOW_WRITES=1. Direct MCP registration remains read-only unless you explicitly enable writes.

Other Plugin Hosts

The repository also carries host-specific marketplace and plugin manifests for Hermes and Antigravity:

Host	Marketplace	Plugin manifest	MCP config
Claude Code	.claude-plugin/marketplace.json	.claude-plugin/plugin.json	.mcp.json
Codex	.agents/plugins/marketplace.json	.codex-plugin/plugin.json	.codex-plugin/mcp.json
Hermes	.hermes-plugin/marketplace.json	.hermes-plugin/plugin.json	.hermes-plugin/mcp.json
Antigravity	.antigravity-plugin/marketplace.json	.antigravity-plugin/plugin.json	.antigravity-plugin/mcp_config.json

1. Get a YNAB Personal Access Token