Built with the MonarchMoneyCommunity Python library - An actively maintained community fork of the Monarch Money API with full MFA support.

🚀 Quick Start

If you plan to use this MCP server locally / on the same computer as Claude Desktop or similar, start with the Local Installation section.

For other deployment scenarios - like containerized deployment or cloud hosting - start with the Containerized Deployment section.

1. Local Installation

1. Clone this repository:

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

1. Install dependencies:

uv sync --locked

--locked installs exactly what uv.lock pins, verified against the hashes it records, and refuses to re-resolve. Without it, uv sync is free to pick up whatever versions happen to satisfy the ranges today.

Using pip:

pip install -r requirements-lock.txt --require-hashes
   pip install -e . --no-deps

requirements-lock.txt is generated from uv.lock and pins every transitive dependency with hashes, so --require-hashes gives the pip path the same guarantee as the uv one. --no-deps on the second command stops pip re-resolving what the first command just pinned.

pip install -r requirements.txt still works and installs exactly the same set. That file is now a one line include of requirements-lock.txt, kept so existing setups and scripts do not break. The pins moved out of it because a root requirements.txt gets resolved as an independent manifest, which had started producing a pinned set that disagreed with uv.lock.

1. Configure Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
     "mcpServers": {
       "Monarch Money": {
         "command": "/opt/homebrew/bin/uv",
         "args": [
           "run",
           "--locked",
           "--project",
           "/path/to/your/monarch-mcp-server",
           "monarch-mcp-server"
         ]
       }
     }
   }

Important: Replace /path/to/your/monarch-mcp-server with your actual path!

uv run --locked --project resolves dependencies from the repo's uv.lock, and monarch-mcp-server is the console script declared in pyproject.toml. --locked matters: without it, a lockfile that has drifted from pyproject.toml is silently re-resolved against PyPI and the recorded hashes stop being enforced. With it, drift is a startup error. Earlier versions of this README used uv run --with 'mcp[cli]', which builds a fresh unpinned environment on every launch and silently picks up whatever the newest release happens to be. That is what broke every install when the MCP SDK published 2.0, and the client only reported it as the server disconnecting. Pinning the launch to the lockfile means a new upstream release cannot change what your server runs.

1. Restart Claude Desktop

1. Configure Claude Code (CLI):

Global (all projects):

macOS/Linux: ~/.claude.json

Windows: %USERPROFILE%\.claude.json

{
     "mcpServers": {
       "Monarch Money": {
         "command": "/opt/homebrew/bin/uv",
         "args": [
           "run",
           "--locked",
           "--project",
           "/path/to/your/monarch-mcp-server",
           "monarch-mcp-server"
         ]
       }
     }
   }

Project-level (specific directory):

Create .mcp.json in your project directory:

{
     "Monarch Money": {
       "command": "/opt/homebrew/bin/uv",
       "args": [
         "run",
         "--locked",
         "--project",
         "/path/to/your/monarch-mcp-server",
         "monarch-mcp-server"
       ]
     }
   }

If installed via pip instead of uv, use:

{
     "command": "python",
     "args": ["/path/to/your/monarch-mcp-server/src/monarch_mcp_server/server.py"]
   }

Important: Replace /path/to/your/monarch-mcp-server with your actual path!

1. Restart Claude Code

2. One-Time Authentication Setup

Important: For security and MFA support, authentication is done outside of Claude.

Open a terminal and run:

cd /path/to/your/monarch-mcp-server
uv run python login_setup.py        # or: python login_setup.py

The script offers three login paths:

Option 1 (recommended): Session cookies from your browser

Long-lived sessions, supports SSO accounts, and sidesteps Cloudflare CAPTCHA gates on programmatic login. Steps:

1. Log in to https://app.monarch.com in Chrome or Firefox.
2. Open DevTools (F12) → Network tab.
3. Click any request whose Name starts with graphql (or any request to api.monarch.com).
4. Scroll to Request Headers, find the cookie: header, and copy the full value.
5. Save it to the cookie file for your platform (recommended), then re-run the script — it reads the file automatically:

mkdir -p ~/.config/monarch-mcp
   # paste the cookie value into the file with your editor, then:
   chmod 600 ~/.config/monarch-mcp/cookie.txt

Windows — %APPDATA%\monarch-mcp\cookie.txt:

New-Item -ItemType Directory -Force "$env:APPDATA\monarch-mcp" | Out-Null
   notepad "$env:APPDATA\monarch-mcp\cookie.txt"   # paste the cookie value, save, close

Files under your user profile are already ACL-restricted to your account on Windows; no chmod equivalent is needed for typical single-user machines.

To use a different location on any platform, set the MONARCH_MCP_COOKIE_FILE environment variable to the full path.

Alternatively, paste the value at the interactive prompt — but note that POSIX terminals silently truncate pasted input at the canonical-mode buffer limit (MAX_CANON, 1024 bytes on macOS/Linux), and real Monarch cookie headers are usually longer than that, so the prompt path fails with a confusing auth error for most users. The cookie file has no length limit and survives repo updates.

The script verifies the cookies against the live API before saving them to your system keyring. The cookie file is only read at setup time; the running MCP server uses the keyring session.

Option 2: Email and password

Standard interactive login. The script handles:

• Email verification codes (Monarch may send one for a new device session even when MFA is off).
• TOTP MFA codes if you have MFA enabled.
• Cloudflare CAPTCHA detection: if Monarch blocks programmatic login, the script tells you to switch to option 1.

Option 3: Legacy session token paste

Kept for users with an existing token captured before the May 2026 API change. Monarch may no longer accept token-only auth on the GraphQL endpoint; if the verification call returns 401, fall back to option 1.

3. Start Using

Once authenticated, use these tools directly in Claude Desktop or Claude Code:

• get_accounts - View all your financial accounts
• get_transactions - Recent transactions with filtering
• get_budgets - Budget information and spending
• get_cashflow - Income/expense analysis

Containerized Deployment

The Docker image uses Astral's uv/Python 3.12 slim base, installs from uv.lock, and defaults to HTTP on 0.0.0.0:8000 inside the container.

Build the image

docker build -t monarch-mcp-server .

Authenticate

Authenticate once using a persistent session volume:

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

The login script supports a cookie file for browser-cookie authentication. To use it, also mount your cookie file at /tmp/monarch-cookie.txt:ro and set MONARCH_MCP_COOKIE_FILE=/tmp/monarch-cookie.txt for the login container.

The file must be readable by the container's uid 10001, which conflicts with the chmod 600 advised for the local flow: a 0600 file owned by your host user is not readable by uid 10001 inside the container. For the container login, either chown 10001 cookie.txt and keep it at 0600, or run the login container with --user $(id -u) so it reads the file as you. Do not widen it to 0644. Delete the file once the login has succeeded.

Once saved, the session volume is sufficient for normal server launches.

[!IMPORTANT]

The session is stored unencrypted in that volume. This differs from a

local install, and the difference is easy to miss.

> On macOS and Windows the session goes to the system keyring. A container has

no keyring backend, so storage falls back to a file. That file is encrypted

at rest only on Windows, through DPAPI, so in a Linux container it holds your

Monarch session in plaintext. Permissions are as tight as a file can be, mode

0600 inside a 0700 directory owned by uid 10001, but file permissions do not

help against anyone who can reach the volume from outside the container.

> Treat monarch-session as a secret. It can be read by root on the Docker

host, by any user in the docker group, by any other container that mounts

the same volume, by docker cp and docker exec, and by anything that backs

up /var/lib/docker. A Monarch session grants full read and write access to

your accounts and does not expire on its own, so a copy of this volume is a

lasting credential. Back it up only to somewhere you would keep a password,

and delete the volume with docker volume rm monarch-session when you are

done with it.

> The cookie file described below is the same kind of secret. Delete it once

the login has succeeded; it is only needed for that one run.

Start the HTTP server

Reuse the session volume when starting the server:

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

Connect your MCP client to http://127.0.0.1:8000/mcp using Streamable HTTP. See HTTP transport configuration for all settings.

The image runs in read only mode by default, because the HTTP transport does not authenticate callers. Anything that can reach the port would otherwise be able to call monarch_logout, or monarch_login_with_token to swap your saved session for another Monarch account. Login happens in the separate login_setup.py container above, so the running server never needs those tools.

To allow writes, add -e MONARCH_MCP_READ_ONLY=0. That registers every mutating tool, including the login and logout tools, on the listening socket, so only do it where every client that can reach the port is trusted.

Connect from another machine

[!WARNING]

This MCP server is not multi-user or multi-account. All connected clients share the same session and permissions.

Ensure that you understand the security implications before exposing the server to a network.

To connect from another machine, put the container behind an authenticated HTTPS reverse proxy or a private network with access controls, publish the port on the appropriate interface, and allow the hostname used by the client:

docker run -d --name monarch-mcp --restart unless-stopped \
  -p 127.0.0.1:8000:8000 \
  -e MONARCH_MCP_ALLOWED_HOSTS=mcp.example.com \
  -v monarch-session:/home/app/.monarch-mcp-server \
  monarch-mcp-server

Here a reverse proxy on the Docker host forwards https://mcp.example.com/mcp to http://127.0.0.1:8000/mcp, preserving the public Host header.

The proxy must support streaming responses without buffering. For direct access on a private network, allow the client's Host value including the port, such as server.lan:8000.

Let me stress this point: This is a single-account server! All connected clients share the same saved Monarch session and permissions, including enabled write tools. Basic Host/origin checks protect against DNS rebinding; they do not authenticate callers. Use one server and session volume per Monarch account if you need to.

Use STDIO instead

To run the Docker image over STDIO instead:

docker run --rm -i \
  -e MONARCH_MCP_TRANSPORT=stdio \
  -v monarch-session:/home/app/.monarch-mcp-server \
  monarch-mcp-server

HTTP Transport Configuration

The server supports MCP Streamable HTTP at /mcp but only when explicitly selected:

uv run --locked monarch-mcp-server --transport http --host 127.0.0.1 --port 8000

Connect an MCP client using Streamable HTTP to http://127.0.0.1:8000/mcp.

| Setting | CLI flag | Environment variable | Default outside Docker | | ---------------------------------- | ------------------------------- | ----------------------------------------------- | ---------------------------------------------- | | Transport | --transport | MONARCH_MCP_TRANSPORT | stdio (http aliases streamable-http) | | Listen address | --host | MONARCH_MCP_HOST | 127.0.0.1 | | Listen port | --port | MONARCH_MCP_PORT | 8000 | | Additional allowed Host headers | --allowed-host (repeatable) | MONARCH_MCP_ALLOWED_HOSTS (comma-separated) | None; loopback hosts are always allowed | | Additional allowed browser Origins | --allowed-origin (repeatable) | MONARCH_MCP_ALLOWED_ORIGINS (comma-separated) | None; HTTP loopback origins are always allowed |

CLI flags override their environment settings. Host entries include the port when clients send one; server.lan:* allows any port. Origin entries include the scheme, for example https://client.example.com. Clients without an Origin header are supported. Browser clients may additionally require CORS handling at the reverse proxy.

Meta Muse

Works great with Meta Muse, Meta's AI assistant, alongside Claude Desktop and Claude Code. Muse speaks MCP, so it connects the same way as any other client: give it the stdio launch command from the installation section, or point it at the Streamable HTTP endpoint if you are running the container.

Using Muse? Ask it to install this server from this repo. Muse can handle the install and register the server with itself, but authentication is a step only you can do: run login_setup.py once and paste a browser cookie, or enter your password and MFA. After that, ask Muse to list your Monarch accounts to confirm it is working.

Check out Muse, your personal AI agent. Redeem my code in Settings within 48 hours of joining and we'll both get 1 billion Muse tokens.

Code: O63W0U

https://muse.ai/join

✨ Features

📊 Account Management

• Get Accounts: View all linked financial accounts with balances and institution info
• Get Account Holdings: See securities and investments in investment accounts
• Refresh Accounts: Request real-time data updates from financial institutions

💰 Transaction Access

• Get Transactions: Fetch transaction data with filtering by date, account, and pagination
• Create Transaction: Add new transactions to accounts
• Update Transaction: Modify existing transactions (amount, description, category, date)

🏷️ Category Management

• Get Categories: List all transaction categories with groups, icons, and metadata
• Get Category Groups: View category groups with their associated categories

📋 Transaction Review

• Get Transactions Needing Review: Find transactions that need attention (uncategorized, no notes, flagged)
• Set Transaction Category: Assign a category to a transaction
• Update Transaction Notes: Add or update notes on transactions (great for receipt links)
• Mark Transaction Reviewed: Clear the needs_review flag on transactions

📦 Bulk Operations

• Bulk Categorize Transactions: Apply a category to multiple transactions at once

🔖 Tag Management

• Get Tags: List all available tags with colors and usage counts
• Set Transaction Tags: Apply tags to a transaction
• Create Tag: Create a new tag with custom name and color

🔍 Advanced Search

• Search Transactions: Comprehensive search with filters for merchant, category, account, tags, date ranges, and amounts
• Get Transaction Details: Retrieve complete details for a single transaction
• Delete Transaction: Remove a transaction
• Get Recurring Transactions: View upcoming recurring transactions

🤖 Transaction Rules (Auto-Categorization)

• Get Transaction Rules: List all auto-categorization rules
• Create Transaction Rule: Create rules with merchant/amount conditions to auto-categorize
• Update Transaction Rule: Modify existing rules
• Delete Transaction Rule: Remove a rule

Recurring forecasts and synced bills

get_recurring_transactions() includes merchant forecasts **and synced liability bills** (such as credit cards and loans). Set include_liabilities=False to request only merchant recurring items. Omit both dates for the current calendar month, or provide both start_date and end_date in YYYY-MM-DD format.

The default response remains a JSON list with the existing merchant fields. Each item also exposes account_id, category_id, amount_diff, and the stream's name and merchant_id. A liability item can have a null merchant. Its stream.credit_report_liability_account contains the liability id, linked account_id/account name, and last_statement with id, due_date, bill_amount, minimum_payment_amount, payment_status, and remaining_balance. Missing statements and unknown balances stay null; paid balances stay zero.

These are not interchangeable amounts. The item's amount and stream's amount are recurring forecasts. last_statement.bill_amount is the original synced statement amount; remaining_balance is the remaining synced statement balance. The latest statement's due date can differ from the forecast item's date. Payment status is returned as supplied by Monarch, not inferred. These values reflect the latest sync, not a guaranteed real-time amount owed.

Merchant forecasts and liability bills can describe the same payment. The tool preserves both with their identities: it does not sum, deduplicate, or substitute forecast amounts for unknown statement balances.

With limit omitted, the tool reads every page itself and returns the complete range, so the default list is the whole month. Pass limit to read a single page instead, and use include_metadata=True to opt into the standard envelope (data, args, count, total_count, truncated, tool, search):

get_recurring_transactions(
    start_date="2026-02-01", end_date="2026-02-28",
    include_liabilities=True, limit=100, offset=0, include_metadata=True,
)

The API supplies no total, so total_count is null. With an explicit limit, a full page is conservatively marked truncated=True (more rows may exist). Keep the dates and filters fixed, advance offset by count, and continue until truncated=False. An exactly full final page requires one more request, which may return an empty page.

Synced bills require bill sync to be available and configured in Monarch; the tool does not enable it or refresh institutions.

🔄 Merchant & Recurring Stream Management

• Get Merchant: View a merchant's details including recurring transaction stream configuration
• Update Merchant: Modify a merchant's name and/or recurring stream settings (frequency, amount, base date)
• Review Recurring Stream: Accept, ignore, or reset recurring transaction streams detected by Monarch

✂️ Transaction Splits

• Get Transaction Splits: View how a transaction has been split into parts
• Split Transaction: Divide a single transaction into multiple parts with different categories or merchants

💵 Budget Management

• Get Budgets: Access budget information including spent amounts and remaining balances by category
• Set Budget Amount: Create or modify budget amounts for any category or category group

📈 Net Worth Tracking

• Get Net Worth: Track total net worth over time with daily snapshots and trend analysis
• Get Account Balance History: View historical balance data for any account
• Get Net Worth by Account Type: See net worth breakdown across account types (checking, savings, investments, etc.)

📊 Financial Analysis

• Get Cashflow: Analyze financial cashflow over specified date ranges with income/expense breakdowns
• Get Transactions Summary: Quick high-level statistics about your transactions
• Get Spending Summary: Spending breakdown by category with totals

🔐 Secure Authentication

• One-Time Setup: Authenticate once, use for weeks/months
• Email OTP Support: Handles Monarch's email verification flow for new devices/sessions
• MFA Support: Full support for two-factor authentication
• SSO/Google sign-in: Use monarch_login_with_token to paste a session token from your browser
• Session Persistence: No need to re-authenticate frequently
• Secure: Credentials never pass through Claude

🛠️ Available Tools

All 60 registered tools. Required parameters are listed first, optional ones are marked with a trailing question mark. This table is generated from the live tool registry and the functions' signatures, so it does not drift.

| Tool | Description | Parameters | | --------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | add_transaction_tag | Add a tag to a transaction, preserving any tags already on it | transaction_id, tag_id | | bulk_categorize_transactions | Apply the same category to multiple transactions at once | transaction_ids, category_id, mark_reviewed?, dry_run? | | bulk_update_transactions | Apply the same edit to many transactions in one request | transaction_ids, category_id?, merchant_name?, notes?, goal_id?, needs_review?, business_entity_id?, dry_run? | | categorize_transaction | Assign a category to a transaction | transaction_id, category_id | | check_auth_status | Report the stored session and its auth mode | None | | create_transaction | Create a new transaction in Monarch Money | date, account_id, amount, merchant_name, category_id, notes?, update_balance? | | create_transaction_category | Create a new transaction category | group_id, transaction_category_name, icon?, rollover_enabled?, rollover_type? | | create_transaction_rule | Create a new transaction auto-categorization rule | merchant_criteria_operator?, merchant_criteria_value?, merchant_criteria_values?, merchant_criteria?, original_statement_operator?, original_statement_values?, original_statement_criteria?, use_original_statement?, amount_operator?, amount_value?, amount_lower?, amount_upper?, amount_is_expense?, set_category_id?, set_merchant_name?, add_tag_ids?, link_goal_id?, hide_from_reports?, review_status?, set_business_entity_id?, account_ids?, category_ids?, apply_to_existing? | | create_transaction_tag | Create a new transaction tag | name, color | | debug_session_loading | Diagnose session loading problems | None | | delete_transaction | Delete a transaction from Monarch Money | transaction_id | | delete_transaction_rule | Delete a transaction rule | rule_id | | get_account_balance_history | Get historical balance data for a specific account | account_id | | get_account_holdings | Get investment holdings for a specific account | account_id | | get_account_sync_health | Report the health of each linked institution connection | stale_after_days? | | get_accounts | Get all financial accounts from Monarch Money | None | | get_budget_summary | Read category/group budgets and authoritative totals without double-counting | start_date?, end_date? | | get_category_group_details | Read a group, its categories and budgeting mode | group_id | | create_transaction_category_group | Create a group with duplicate prevention and verified readback | name, group_type?, dry_run? | | update_transaction_category_group | Rename a group or switch group/category budgeting, with preview and readback | group_id, name?, group_level_budgeting_enabled?, dry_run? | | get_budgets | Get budget information from Monarch Money | start_date?, end_date? | | get_business_entities | List the business entities on the Monarch account (id and name) | None | | get_cashflow | Get cashflow analysis from Monarch Money | start_date?, end_date? | | get_cashflow_by_month | Get spending trends over time, broken down by category and month | start_date, end_date | | get_category_details | Get a single category's details including budget amounts for a month | category_id, month? | | get_debt_paydown | Get the debt paydown plan and the accounts feeding it | method? | | get_goal_contributions | Show a goal's budgeted contributions, broken down by funding account | goal_id, month? | | get_goals | List Monarch savings and debt-paydown goals | None | | get_merchant | Get a merchant's details including recurring transaction stream configuration | merchant_id | | get_net_worth | Get net worth history over time | start_date?, end_date?, account_type? | | get_net_worth_by_account_type | Get net worth breakdown by account type over time | start_date, timeframe? | | get_recurring_transactions | Get upcoming recurring transactions | start_date?, end_date?, include_liabilities?, limit?, offset?, include_metadata? | | get_spending_summary | Get a spending summary broken down by category, category group, and merchant | start_date?, end_date? | | get_transaction_categories | Get all available transaction categories from Monarch Money | None | | get_transaction_category_groups | Get all transaction category groups (parent groupings for categories) | None | | get_transaction_details | Get full details for a specific transaction | transaction_id | | get_transaction_rules | Get all transaction auto-categorization rules from Monarch Money | None | | get_transaction_splits | Get the splits for a transaction | transaction_id | | get_transaction_tags | Get all available transaction tags from Monarch Money | None | | get_transactions | Get transactions from Monarch Money | limit?, offset?, start_date?, end_date?, account_id?, search?, category_ids?, `ca

... (README truncated for length)