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.
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
Clone this repository:
git clone https://github.com/robcerda/monarch-mcp-server.git
cd monarch-mcp-server
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.
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.
Configure Claude Desktop:
Add this to your Claude Desktop configuration file:
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.
Restart Claude Desktop
OR
Configure Claude Code (CLI):
Add this to your Claude Code configuration file:
Click any request whose Name starts with graphql (or any request to api.monarch.com).
Scroll to Request Headers, find the cookie: header, and copy the full value.
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
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:
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:
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:
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.
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.
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):
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
Use get_accounts to show me all my financial accounts
Get Recent Transactions
Show me my last 50 transactions using get_transactions with limit 50
get_transactions returns a JSON object with tool, args, count, total_count, truncated, search, and data so large agent-tools/<uuid>.txt responses are self-describing. Transaction rows live in data and include original_statement / plaid_description when Monarch provides the underlying Plaid statement text, plus currency, direction, direction_source, transaction_type, category_group, and category_group_id when those values can be derived from Monarch response data. When Monarch's server-side search errors or returns no rows, wide_search scans recent transactions locally across merchant, original statement, description, notes, category, account, and tags. Transactions hidden from reports are included by default and carry hide_from_reports: true; Monarch's API leaves them out unless asked, so pass include_hidden=false only when you want just the transactions Monarch's reports count. get_transactions_needing_review takes the same include_hidden flag, and search_transactions returns both kinds when hidden_from_reports is left unset.
Check Spending vs Budget
Use get_budgets to show my current budget status
Set a Budget Amount
Set my grocery budget to $600 for this month using set_budget_amount
Apply Budget to All Future Months
Set my entertainment budget to $150 and apply it to all future months using set_budget_amount with apply_to_future=true
Track Net Worth Over Time
Show my net worth trend for the past year using get_net_worth
View Account Balance History
Show me how my savings account balance has changed over time using get_account_balance_history
Net Worth Breakdown by Account Type
Show my net worth breakdown by account type using get_net_worth_by_account_type
Analyze Cash Flow
Get my cashflow for the last 3 months using get_cashflow
List Available Categories
Show me all available categories using get_transaction_categories
Review Uncategorized Transactions
Show me transactions from the last 7 days that need review using get_transactions_needing_review
Bulk Categorize Transactions
Categorize these three transactions as "Groceries" using bulk_categorize_transactions
Tag a Transaction
Add the "Tax Deductible" tag to this transaction using set_transaction_tags
Search for Transactions
Find all Amazon transactions from the last month using search_transactions
View Recurring Bills
Show me my upcoming recurring transactions using get_recurring_transactions
Create Auto-Categorization Rule
Create a rule to automatically categorize Amazon transactions as "Shopping" using create_transaction_rule
Split a Transaction
Split this $100 Costco transaction into $60 for Groceries and $40 for Household using split_transaction
Get Transaction Statistics
Give me a quick summary of my transactions using get_transactions_summary
View Spending by Category
Show my spending breakdown by category for last month using get_spending_summary
Update a Recurring Bill Amount
Update PennyMac's recurring stream to $1,460.93 monthly using update_merchant
Review Recurring Streams
Approve the Netflix recurring stream using review_recurring_stream
📅 Date Formats
All dates should be in YYYY-MM-DD format (e.g., "2024-01-15")
Transaction amounts: positive for income, negative for expenses
🔧 Troubleshooting
Authentication Issues
If you see "Authentication needed" errors:
Run the setup command: cd /path/to/your/monarch-mcp-server && python login_setup.py (or uv run python login_setup.py)
Restart Claude Desktop or Claude Code
Try using a tool like get_accounts
Email Verification Required
Monarch may require an email one-time code for a new device or session, even if MFA is not enabled. If you see an email-code prompt:
Check the email address on your Monarch account
Enter the one-time code in login_setup.py
Let the script finish so it can save the reusable token to your system keyring
Session Expired or 401 within an hour
If your session dies quickly (under a couple of hours), the most common cause is that Monarch returned a short-lived token. The login script now requests trusted_device=True and rejects any short-lived token, so a fresh login produces a long-lived session. If you re-run login_setup.py and the issue persists, switch to option 1 (browser cookies); cookie sessions track the lifetime of the underlying browser login.
Cloudflare CAPTCHA on login
If login_setup.py reports "Programmatic login is blocked by Cloudflare CAPTCHA", choose option 1 (browser cookies) instead. Email/password POSTs to Monarch's login endpoint are sometimes gated by Cloudflare for unfamiliar IPs or rapid retries; cookie-based auth bypasses that endpoint entirely.
'Context' object has no attribute 'elicit'
The monarch_login and monarch_login_with_token tools require the MCP Python SDK 1.10.0 or newer (released June 2025). If your environment cached an older mcp install, refresh it:
uv cache clean mcp
Then fully quit and reopen Claude Desktop or Claude Code so it relaunches the server with a fresh resolution. As a fallback while you upgrade, run python login_setup.py from the repo to authenticate via the terminal.
Common Error Messages
"No valid session found": Run python login_setup.py (or uv run python login_setup.py)
"Monarch sent a one-time code to your email": Run python login_setup.py and complete email verification
"Invalid account ID": Use get_accounts to see valid account IDs
"Date format error": Use YYYY-MM-DD format for dates
Session tokens are stored securely in the system keyring (with an automatic file fallback for environments without a keyring backend)
The device-uuid captured at login is stored alongside the token so it reloads cleanly
Sessions persist across Claude Desktop and Claude Code restarts
No need for frequent re-authentication
Security Features
Credentials never transmitted through Claude Desktop or Claude Code
MFA/2FA fully supported
Email verification codes are handled only in the terminal setup script
Session tokens are stored in the system keyring
Authentication handled in secure terminal environment
Strongest option: read only mode
Set MONARCH_MCP_READ_ONLY=1 in the server's environment and the mutating
tools are never registered. They do not appear in the tool list and cannot be
called at all, which is stronger than an approval prompt: a model that was
talked into a write by a merchant name or memo it read back cannot invoke a
tool that is not there.
This leaves 30 of the 58 tools available, covering everything that reads.
Read only is off by default outside Docker, so existing setups are unaffected;
the Docker image turns it on (see Start the HTTP server). Note that it
also removes the login and logout tools, since those change durable state, so
authenticate with login_setup.py before enabling it.
Recommended: require approval for mutating tools
These tools mutate your Monarch data. The list is every registered tool that writes, checked against the source rather than maintained by hand:
refresh_accounts is side effecting too, since it posts a refresh request to your institutions, though it does not change your ledger.
Because the LLM can be influenced by data it reads back (a malicious-looking memo or merchant name in a transaction), the safest setup is to configure your MCP client to require manual approval before any mutating tool runs. In Claude Desktop and Claude Code this is the default behavior for unknown tools; keep it that way for the tools listed above rather than allow-listing them.
bulk_categorize_transactions, bulk_update_transactions, upload_account_balance_history, update_account and update_category accept a dry_run=True argument that returns the planned changes without executing them, useful for previewing before approving.
update_category additionally requires confirm_rollover_reset=True before rollover_start_month or rollover_starting_balance will be applied. Those two restart a category's rollover period and discard the balance accumulated in it, which cannot be undone, so they cannot ride along unnoticed in a call that otherwise reads like a rename.
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Monarch?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Monarch precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte Monarch usa?
Monarch roda localmente via stdio.
Quando Monarch foi verificado pela última vez?
Última verificação: 2026-10-26. MCP Server for use with Monarch Money