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, plus a refresh tool to sync from the Monarch API. Works with Claude Code, Claude Desktop, and any MCP-compatible client.

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

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