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.

• 149 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.

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-mcp

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 4 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.

• update_rule genuinely supports partial updates: the Monarch update mutation silently ignores partial inputs (while reporting success), so the tool fetches the rule's current state, merges your fields over it, converts read shapes to write shapes (category/tag objects → IDs, merchant object → name), and sends the complete input. Goal-link, business-entity, notification, and needs-review-by-user actions are not round-tripped and may be reset by an update.

• delete_rule treats the absence of API errors as success: Monarch's deleted response field is unreliable (it reports false even for successful deletes) and is echoed only as apiDeletedField for debugging.

• Recurring streams have no local mirror table — all three recurring tools talk to the live API (Monarch models recurring as merchant-level RecurringTransactionStreams; the mirror's per-transaction is_recurring flag is derived from stream membership). The stream write tools self-verify: review_recurring_stream checks the mutation's returned reviewStatus, and mark_stream_not_recurring re-fetches the stream list and confirms the stream is gone. Note: Monarch's stream resolvers silently no-op on unknown IDs (no GraphQL error; success: false / stream: null) — both tools surface that as a failed verification rather than success.

• Budgets have no local mirror table — get_budget and set_budget_amount both talk to the live API. Budget amounts use the positive-spend convention (planned 445 = plan to spend $445), the opposite of transaction amounts. set_budget_amount self-verifies by re-reading the month's budget after the write and comparing the planned amount (verification.verified in the result). Group-level targets require groupLevelBudgetingEnabled on the group; flex: true requires the fixed_and_flex budget system.

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