monarch-mcp

MCP server for querying and managing Monarch Money personal finance data.

Provides read-only SQL access to your transactions via a local SQLite mirror, a refresh tool to sync from the Monarch API, and write tools to update, split, tag, and rule-manage transactions in your live Monarch account. Works with Claude Code, Claude Desktop, and any MCP-compatible client.

What Makes This Different

Most Monarch Money MCP servers are API passthroughs — each tool call hits the live Monarch API and returns the full response. This server takes a fundamentally different approach:

• Local SQLite mirror — transactions are synced to a local database, so queries are instant with zero API latency. No other Monarch MCP does this.

• Arbitrary SQL — instead of fixed-parameter tools like get_transactions(start_date, end_date, limit), you get query_transactions(sql) and can write any SELECT query: JOINs, CTEs, window functions, aggregations. The AI writes the query it needs, not the query a tool designer anticipated.

• MCP Resources — the only Monarch MCP that exposes schema, accounts, categories, and tags as MCP resources. This gives AI clients the metadata they need to write good queries without burning tool calls.

• Token-efficient — pre-computed resources and SQL-level filtering mean only relevant data crosses the wire. Other servers return full API payloads on every call.

• Zero native dependencies — uses Node.js built-in node:sqlite, no compiled extensions. Just npm install and go.

• 212 tests — fixture-based test suite with no dependency on real financial data; write tools are tested against a mocked API.

• Write tools — update, split, and tag transactions, and manage auto-categorization rules, directly against the live Monarch API. Designed for the "extension/mirror as read-only sensor, agent as sole writer" architecture.

• Recommendation queue — review and apply extension-generated transaction proposals (splits, renames, categorizations) from a shared local queue.db, with a guarded status lifecycle and double-apply protection.

Trade-off: This server focuses on transactions (SQL analysis + write operations). For budgets, investments, or cashflow, pair it with an API-passthrough MCP like robcerda/monarch-mcp-server.

Related MCP server: Monarch Money MCP Server

Requirements

• Node.js >= 22.0.0 (uses node:sqlite)

• A Monarch Money account with an auth token

Quick Start

# 1. Clone and install
git clone https://github.com/sdeiley/monarch_mcp.git
cd monarch_mcp
npm install

# 2. Initialize data directory
node src/bin/cli.js init

# 3. Set your auth token
export MONARCH_TOKEN=<your-token>

# 4. Fetch your transactions
node src/bin/cli.js refresh

# 5. Start the MCP server
node src/bin/cli.js serve

Getting Your Auth Token

You need a Monarch Money auth token. Options:

1. Environment variable: export MONARCH_TOKEN=<token>

2. Token file: Create ~/.monarch-token with contents: {"token": "<token>"}

To get a token, log into app.monarch.com, open browser DevTools, and find the Authorization: Token <value> header on any GraphQL request.

MCP Configuration

Add to your .mcp.json (Claude Code, Dispatch):

{
  "mcpServers": {
    "monarch": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/monarch_mcp/src/bin/stdio.js"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "monarch": {
      "type": "stdio",
      "command": "npx",
      "args": ["monarch-mcp", "serve"]
    }
  }
}

Resources

The server exposes 5 read-only resources:

Tools

Write tools

The tools marked "(write)" mutate your live Monarch Money account — they are not sandboxed and there is no undo. AI agents should confirm with the user before calling any of them.

Notes:

• The transaction write tools (update_transaction, split_transaction, set_transaction_tags) self-verify and self-sync: after the mutation, the tool re-fetches the transaction from the live API, verifies the requested changes took effect, and upserts the live state (including split children) into the local mirror. The result is { transaction, verification, mirror } — when verification.verified and mirror.synced are both true, no refresh_transactions is needed; otherwise the result carries a warning (and mismatch details) and the mirror is stale for that transaction until refresh_transactions is run. A mismatch usually means a Monarch rule or concurrent edit overrode the change.

• Rule writes (create_rule / update_rule / delete_rule, especially with applyToExistingTransactions) can affect many transactions at once and still leave the mirror stale until refresh_transactions.

• split_transaction validates that split amounts sum exactly to the live parent transaction amount (to the cent) before calling the API. Amounts are negative for expenses.

• set_transaction_tags replaces the complete tag set; include existing tag IDs you want to keep.

• Rule create/update mutations return no rule entity (Monarch API limitation); use list_rules to confirm.

Recommendation Queue

The queue_* tools operate on queue.db in the data directory — a local recommendation queue shared with the Monarch Chrome extension, whose parsing pipeline is the producer: it captures proposed transaction changes (invoice-based splits, merchant renames, categorizations) as queue records with a payload diff, confidence, and reasoning.

The agent-side review workflow:

1. queue_list with status: "pending" — present items to the user grouped by group_key, with confidence and reasoning.

2. After the user approves, queue_apply each approved id (dry_run: true first to preview the mutation plan).

3. queue_sweep occasionally to mark stale records and purge old terminal ones.

queue_apply is safer than the raw write tools for queued items: it re-fetches the live transaction and refuses (marking the record stale) if the transaction already carries the "Ext Processed" tag or has splits, validates split sums against the live amount, sets "Ext Processed" on success, and records the outcome (applied / failed) with a guarded status transition so double-apply is impossible — even if the extension raced it. After a successful apply, the target transaction is re-fetched and synced into the local mirror (mirror in the result). Status lifecycle: pending → applied|dismissed|stale, failed → pending for retry; applied/dismissed are terminal.

The queue database is created lazily; if the extension side isn't installed the queue tools simply report an empty queue.

Transaction Table Columns

id, amount, date, merchant_name, plaid_name, category_name, category_group, category_type, account_name, notes, tags, is_split, parent_id, pending, is_recurring

Amounts are negative for expenses, positive for income.

Example Queries

-- Spending by category this month
SELECT category_name, COUNT(*) AS n, ROUND(SUM(amount), 2) AS total
FROM transactions
WHERE date >= '2026-03-01' AND category_type = 'expense'
GROUP BY category_name ORDER BY total

-- Uncategorized transactions
SELECT date, merchant_name, amount FROM transactions
WHERE category_name = 'Uncategorized' AND date >= '2026-01-01'

-- Top merchants by spend
SELECT merchant_name, COUNT(*) AS n, ROUND(SUM(amount), 2) AS total
FROM transactions WHERE amount < 0
GROUP BY merchant_name ORDER BY total LIMIT 10

CLI Commands

monarch-mcp init      # Create ~/.monarch/ data directory
monarch-mcp refresh   # Fetch recent transactions (3 months)
monarch-mcp refresh --full  # Fetch all transaction history
monarch-mcp serve     # Start stdio MCP server
monarch-mcp --help    # Show help

Environment Variables

Development

npm test              # Run all tests
node --test test/db.test.js  # Run specific test file

License

MIT