Monarch Money MCP Server

A Model Context Protocol (MCP) server for integrating with the Monarch Money personal finance platform. This server provides seamless access to your financial accounts, transactions, budgets, and analytics through Claude Desktop and Claude Code.

My MonarchMoney referral: https://www.monarchmoney.com/referral/ufmn0r83yf?r_source=share

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

🚀 Quick Start

1. Installation

1. Clone this repository:

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

2. Install dependencies:

   Using uv (recommended):

   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.

3. Configure Claude Desktop: Add this to your Claude Desktop configuration file:

   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.

4. Restart Claude Desktop

OR

3. Configure Claude Code (CLI): Add this to your Claude Code configuration file:

   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!

4. 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:

   macOS / Linux — ~/.config/monarch-mcp/cookie.txt (respects $XDG_CONFIG_HOME):

   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.

The resulting long-lived session token is saved to your system keyring.

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

✨ 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-categ