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

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

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:

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.