Monarch Money MCP Server + HTTP Proxy

Read-only access to Monarch Money financial data via two interfaces:

• MCP Server — stdio-based, for local use with Claude Desktop / Claude Code

• HTTP Proxy — FastAPI REST API, for remote access over Tailscale or any network

Note: This is a personal project, not affiliated with Monarch Money. Built for learning about spending patterns and projections. All access is read-only.

Important: Upstream Library Fix

The original monarchmoney Python package (by hammem) is abandoned and broken — Monarch rebranded their API from api.monarchmoney.com to api.monarch.com, causing HTTP 525 errors. This project uses monarchmoneycommunity, the maintained community fork.

Related MCP server: Monarch Money MCP Server

Features

• Read-only access to all Monarch Money accounts

• Transaction analysis with date filtering and search

• Budget tracking and cashflow analysis

• Account details including investment holdings

• Secure authentication with MFA/TOTP support

• Session persistence to minimize re-authentication

• HTTP proxy for remote access from any device on your network

Installation

Prerequisites

• Python 3.13+

• uv package manager

• A Monarch Money account

Setup

1. Clone the repository:

   git clone https://github.com/rmarji/monarch-mcp-server.git
   cd monarch-mcp-server

2. Install dependencies:

   uv sync

3. Configure credentials:

   cp .env.example .env

   Edit .env:

   MONARCH_EMAIL=your-email@example.com
   MONARCH_PASSWORD=your-monarch-password
   MONARCH_MFA_SECRET=your-totp-secret-key

   The MONARCH_MFA_SECRET is the base32 TOTP secret from your authenticator app setup. This is required if your account has 2FA enabled (Monarch may require it by default).

Usage

HTTP Proxy (Remote Access)

Start the FastAPI proxy:

uv run python monarch_http_proxy.py

This binds to 0.0.0.0:8765 and is accessible from any device on your network (e.g., over Tailscale).

Endpoints

Examples

curl http://localhost:8765/health
curl http://localhost:8765/accounts
curl http://localhost:8765/transactions?limit=5
curl http://localhost:8765/transactions?start_date=2026-01-01&end_date=2026-01-31
curl "http://localhost:8765/transactions/search?q=grocery"
curl http://localhost:8765/cashflow?start_date=2026-01-01&end_date=2026-03-01

The port can be changed via MONARCH_PROXY_PORT in .env (default: 8765).

MCP Server (Claude Desktop / Claude Code)

Start the MCP server:

uv run python run_server.py

Claude Desktop Integration

Add to your claude_desktop_config.json:

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

MCP Resources

• monarch://accounts — All linked accounts

• monarch://transactions/recent — Last 100 transactions

• monarch://budgets — Budget information with actual vs target

• monarch://cashflow/summary — Income, expenses, and savings summary

MCP Tools

• get_transactions — Transactions with date range filtering

• get_account_details — Detailed account info including holdings

• get_cashflow_analysis — Cashflow analysis by category and time period

• search_transactions — Search by description or merchant

• get_categories — All transaction categories

• get_institutions — Linked financial institutions

Project Structure

monarch-mcp-server/
├── monarch_http_proxy.py    # FastAPI HTTP proxy for remote access
├── monarch_mcp_server.py    # MCP server implementation
├── run_server.py            # MCP server launcher
├── debug_server.py          # Authentication debugging
├── test_api.py              # API connection testing
├── tests/
│   └── test_monarch_mcp_server.py
├── pyproject.toml
├── .env.example
└── .gitignore

Security

• No write operations — entirely read-only

• Credentials stay local — .env and session files are gitignored

• Session caching — authenticates once, reuses session via .mm/mm_session.pickle

• MFA/TOTP support — auto-generates 2FA codes from your secret key

• No auth on HTTP proxy — relies on network isolation (Tailscale, private network, etc.)

Troubleshooting

HTTP 525 / Login Failures

If you see HTTP Code 525, you're likely using the abandoned monarchmoney package. This project requires monarchmoneycommunity:

uv remove monarchmoney
uv add monarchmoneycommunity

MFA Required

Monarch Money may require 2FA even if you didn't explicitly enable it. Add MONARCH_MFA_SECRET to your .env.

Stale Session

Delete the cached session to force a fresh login:

rm -rf .mm/

Testing

uv sync --extra test
uv run pytest tests/ -v

License

MIT License — see LICENSE for details.

Disclaimer

This project is not affiliated with Monarch Money. Use at your own risk and ensure compliance with Monarch Money's terms of service.