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.

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

Clone the repository:

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

Install dependencies:

   uv sync

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: ``bash 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

| Method | Path | Query Params | Description | |--------|------|-------------|-------------| | GET | /health | — | Status and auth check | | GET | /accounts | — | All linked accounts | | GET | /accounts/{id} | — | Account details (includes holdings for investment accounts) | | GET | /transactions | start_date, end_date, account_id, limit | Filtered transactions | | GET | /transactions/search | q (required), start_date, end_date | Search by description/merchant | | GET | /cashflow | start_date, end_date | Cashflow summary and details | | GET | /categories | — | Transaction categories |

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: ``bash 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: ``bash 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: ``bash 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.

Monarch Money MCP Server