Monarch Money MCP Server

An MCP server for Monarch Money — gives AI assistants like Claude access to your financial accounts, transactions, budgets, and more.

Originally forked from @colvint/monarch-money-mcp but has diverged into a full rewrite on a modern FastMCP architecture. It's grown from a handful of tools to a broad toolset — adding server-side transaction search, parallel bulk transaction updates, multi-month spending-pattern analysis with forecasting, and a single-call financial overview that fans out to five Monarch APIs at once. Responses are tuned hard for token efficiency: the default compact transaction format cuts payload size by ~80%, categories return just id+name unless you ask for more, and every tool accepts a verbose flag when you want the full payload. It also ships MCP resources and guided prompts, natural-language date parsing ("last month", "30 days ago"), and proper read/write tool annotations so clients know what's safe to call.

Built on the monarchmoneycommunity library by @bradleyseanf — an actively-maintained community fork that tracks the latest Monarch Money API changes (the api.monarch.com domain move, gql 4.0, auth persistence) with full MFA support, pinned to a specific commit for reproducible builds. It descends from the original monarchmoney library by @hammem, which is no longer actively maintained.

Features

• Tools covering accounts, transactions, budgets, cashflow, investments, categories, recurring transactions, and spending analysis
• Structured output — every tool returns a typed schema (outputSchema + machine-readable structured content) with a text fallback for older clients
• MCP resources for quick access to categories, accounts, and institutions, plus parameterized templates for per-account holdings and history (accounts://{account_id}/holdings|history)
• MCP prompts for guided financial analysis workflows, with live argument autocompletion
• Smart output formatting — compact transaction format reduces token usage by ~80%
• Natural language dates — "last month", "30 days ago", "this year" all work
• Batch operations — parallel multi-account queries, bulk transaction updates, with progress reporting
• Spending analysis — multi-month trend analysis with category/account breakdowns
• Tool annotations & titles — read/write metadata and human-friendly titles for MCP clients

Setup

One-line install, no clone, no absolute-path wrangling. The server is published to PyPI, so uv runs it on demand with uvx monarch-mcp-jamiew. You'll need uv installed and your Monarch credentials (see Getting your MFA secret below).

Standard config

Every MCP client uses the same shape — command uvx, package monarch-mcp-jamiew, and your three credentials as env vars:

{
  "mcpServers": {
    "monarch-money": {
      "command": "uvx",
      "args": ["monarch-mcp-jamiew"],
      "env": {
        "MONARCH_EMAIL": "your-email@example.com",
        "MONARCH_PASSWORD": "your-password",
        "MONARCH_MFA_SECRET": "your-mfa-secret-key"
      }
    }
  }
}

Pick your client below for the exact steps.

claude mcp add monarch-money \
  -e MONARCH_EMAIL=your-email@example.com \
  -e MONARCH_PASSWORD=your-password \
  -e MONARCH_MFA_SECRET=your-mfa-secret-key \
  -- uvx monarch-mcp-jamiew

codex mcp add monarch-money \
  --env MONARCH_EMAIL=your-email@example.com \
  --env MONARCH_PASSWORD=your-password \
  --env MONARCH_MFA_SECRET=your-mfa-secret-key \
  -- uvx monarch-mcp-jamiew

[mcp_servers.monarch-money]
command = "uvx"
args = ["monarch-mcp-jamiew"]
env = { MONARCH_EMAIL = "your-email@example.com", MONARCH_PASSWORD = "your-password", MONARCH_MFA_SECRET = "your-mfa-secret-key" }

mcp_servers:
  monarch-money:
    command: uvx
    args: ["monarch-mcp-jamiew"]
    env:
      MONARCH_EMAIL: "your-email@example.com"
      MONARCH_PASSWORD: "your-password"
      MONARCH_MFA_SECRET: "your-mfa-secret-key"

git clone https://github.com/jamiew/monarch-mcp
cd monarch-mcp
uv sync

{
  "mcpServers": {
    "monarch-money": {
      "command": "/abs/path/to/uv",
      "args": ["--directory", "/abs/path/to/monarch-mcp", "run", "python", "server.py"],
      "env": {
        "MONARCH_EMAIL": "your-email@example.com",
        "MONARCH_PASSWORD": "your-password",
        "MONARCH_MFA_SECRET": "your-mfa-secret-key"
      }
    }
  }
}

[!NOTE] The claude mcp add / codex mcp add one-liners put your credentials in shell history. If that bothers you, edit the client's config file directly (as shown for Claude Desktop / Codex above) instead.

Getting your MFA secret

1. Go to Monarch Money settings and enable 2FA
2. When shown the QR code, look for "Can't scan?" or "Enter manually"
3. Copy the secret key (a string like T5SPVJIBRNPNNINFSH5W7RFVF2XYADYX)
4. Use this as your MONARCH_MFA_SECRET

Tools

Transaction format

By default, transactions return a compact format with the fields that matter:

{
  "id": "123456789012345678",
  "date": "2025-03-15",
  "amount": -12.50,
  "merchant": "Corner Deli",
  "plaidName": "CORNER DELI NYC",
  "category": "Restaurants & Bars",
  "categoryId": "cat_001",
  "account": "Main Credit Card",
  "needsReview": true
}

pending and notes are included only when present. Set verbose=True on any tool for the full API response with all metadata.

Session management

Sessions are cached in ~/.monarch-mcp/ for faster subsequent logins (override the location with the MONARCH_SESSION_DIR env var). If you hit auth issues:

• Delete ~/.monarch-mcp/session.pickle to clear the cached session
• Set MONARCH_FORCE_LOGIN=true in your env config to force a fresh login
• Make sure your system clock is accurate (required for TOTP)

Development

Local setup

Create a .env file (git-ignored):

MONARCH_EMAIL="your-email@example.com"
MONARCH_PASSWORD="your-password"
MONARCH_MFA_SECRET="YOUR_TOTP_SECRET_KEY"

Tests