robcerda/monarch-mcp-server

Monarch Money MCP Server

What it is – A small Python server that talks to the Monarch Money personal‑finance API and exposes the data through the Model Context Protocol (MCP). MCP is the way Claude Desktop, Claude Code and other Anthropic‑based AI agents call external tools. By running this server, you can let an AI read and modify your Monarch accounts, transactions, budgets, tags, etc.

Why you might care – If you use Claude as a personal assistant (e.g., Claude Desktop, Claude Code, Meta Muse) and want it to have direct, programmatic access to your banking/ budgeting data, this server is the bridge. It handles the tricky Monarch MFA/login flow and presents a clean set of commands that the AI can invoke.

Key Features (as listed in the README)

Account management – list accounts, holdings, trigger a refresh.
Transaction CRUD – fetch, create, update, delete, bulk‑categorize, tag, and mark as reviewed.
Category & tag handling – list categories, groups, tags; create new tags.
Search & filters – powerful transaction search with date, amount, merchant, tags, etc.
Recurring forecasts & synced bills – view upcoming recurring payments and liability‑bill details.
Rule engine – list/create/update/delete auto‑categorisation rules.
Multiple transport options – run as a simple stdio‑based tool (default) or expose a Streamable‑HTTP endpoint (/mcp).
Container support – Docker image based on Astral’s uv/Python 3.12 slim, with a persistent volume for the authenticated session.
Integration notes – works with Claude Desktop/Code, Meta Muse, and any MCP‑compatible client.

Quick‑Start (Local)

Clone & install

git clone https://github.com/robcerda/monarch-mcp-server.git
cd monarch-mcp-server
uv sync --locked   # or pip install -r requirements-lock.txt && pip install -e .

Configure your Claude client – add a mcpServers entry pointing to the uv run … monarch-mcp-server command (paths differ on macOS vs Windows; see README for exact JSON).
Authenticate once
```
uv run python login_setup.py   # or python login_setup.py
```
The script lets you:
- Paste a browser session cookie (recommended – avoids Cloudflare CAPTCHA).
- Log in with email/password + MFA.
- Use a legacy token (if you have one). The resulting session token is stored in your OS keyring (or a file inside a Docker container).
Restart Claude – the AI will now see a new "Monarch Money" tool with commands like get_accounts, get_transactions, etc.

Containerized Deployment

Build: docker build -t monarch-mcp-server .

Authenticate (once) using a persistent volume:

docker run --rm -it -v monarch-session:/home/app/.monarch-mcp-server \
    monarch-mcp-server python login_setup.py

Run the server (HTTP mode, read‑only by default):

docker run -d --name monarch-mcp \
    -p 127.0.0.1:8000:8000 \
    -v monarch-session:/home/app/.monarch-mcp-server \
    monarch-mcp-server

Clients connect to http://127.0.0.1:8000/mcp.

Enable writes (dangerous if exposed): add -e MONARCH_MCP_READ_ONLY=0.
Security tip – the session volume stores an unencrypted Monarch token on Linux containers; treat the volume as a secret and delete it when you’re done.

Security & Operational Notes

Single‑account server – all connected clients share the same Monarch session. Do not expose the HTTP endpoint publicly unless you put it behind an authenticated reverse proxy.
Host/origin checks – the server can be limited to specific Host headers via MONARCH_MCP_ALLOWED_HOSTS to mitigate DNS‑rebinding attacks.
Read‑only default – the Docker image runs in read‑only mode; mutating commands (including login/logout) are only registered when MONARCH_MCP_READ_ONLY=0.
Credential storage – on a local install the session lives in the OS keyring; in Docker it falls back to a plain file (encrypted only on Windows via DPAPI). Keep the volume private.
MFA handling – the login script supports TOTP codes and will prompt for verification codes if Monarch asks for them.

Who Might Use This

Power users of Claude who want their AI assistant to manage budgets, categorize spending, or pull transaction data on demand.
Developers building custom AI agents that need a reliable, MCP‑compatible endpoint for personal‑finance data.
Anyone comfortable with a modest amount of command‑line / Docker work and who trusts the security model described above.

Bottom line – The Monarch Money MCP Server is a purpose‑built bridge that lets Claude‑style AI agents interact with your Monarch finance data via a standard protocol, with both local and containerized deployment options and clear guidance on authentication and security.