monarch-mcp 0.1.4

Model Context Protocol (MCP) server for Monarch Money personal finance platform

Monarch Money MCP Server

A Model Context Protocol (MCP) server for integrating with the Monarch Money personal finance platform through Claude Desktop.

Overview

• Secure by design — browser-based login, token stored in OS keychain (never in config files or env vars)
• Safe by default — read-only mode prevents accidental changes; write tools require explicit opt-in
• Comprehensive — 44 tools covering accounts, transactions, splits, budgets, cashflow, tags, categories, transaction rules, recurring merchants, and credit history
• Easy to install — Claude Desktop extension (.mcpb), uvx, or pip

Two operating modes:

The server starts in read-only mode by default. Write tools are hidden and blocked until you explicitly opt in.

	Read-only (default)	Write mode
View accounts, transactions, budgets	Yes	Yes
Analyze cashflow, spending, net worth	Yes	Yes
Create transactions, tags, categories, rules	No	Yes
Update accounts, budgets, splits	No	Yes
Delete transactions, tags, accounts	No	Yes

Quick Start

Installation

Option 1: Claude Desktop Extension (.mcpb) — Recommended for Claude Desktop

Enables toggling write mode on/off directly from the Claude Desktop app.

1. Download the latest .mcpb from Releases
2. In Claude Desktop: Settings > Extensions > Advanced Settings > Install Extensions — select the .mcpb file
3. Restart Claude Desktop

To enable write tools: Settings > Extensions > Monarch Money MCP Server > Configure — toggle "Enable write tools" and click Save.

---

Option 2: uvx (no install required) — Recommended for agents (e.g. Claude Code or Cursor)

Also works with Claude Desktop, but write mode cannot be toggled from the app — set it in the config instead.

Add to your MCP config file:

{
  "mcpServers": {
    "Monarch Money": {
      "command": "uvx",
      "args": ["monarch-mcp"]
    }
  }
}

To enable write tools:

{
  "mcpServers": {
    "Monarch Money": {
      "command": "uvx",
      "args": ["monarch-mcp", "--enable-write"]
    }
  }
}

---

Option 3: pip install — Recommended for local installation and venv

pip install monarch-mcp

Contributors: See docs/releasing.md for the release process, version scheme, and pre-release testing via TestPyPI.

Add to your MCP config using the full path to your Python interpreter:

{
  "mcpServers": {
    "Monarch Money": {
      "command": "/path/to/bin/python3",
      "args": ["-m", "monarch_mcp"]
    }
  }
}

To enable write tools, add "--enable-write" to args.

---

Option 4: Clone and install — Recommended for development

git clone https://github.com/vargahis/monarch-mcp.git
cd monarch-mcp
pip install -e .

Then add to your MCP config using the Python interpreter from your dev environment:

{
  "mcpServers": {
    "Monarch Money": {
      "command": "/path/to/bin/python3",
      "args": ["-m", "monarch_mcp"]
    }
  }
}

To enable write tools, add "--enable-write" to args.

Authentication

Authentication happens automatically in your browser the first time the MCP server starts without a saved session.

1. Start (or restart) Claude Desktop
2. The server detects that no token exists and opens a login page in your browser
3. Enter your Monarch Money email and password
4. Provide your 2FA code if you have MFA enabled
5. Once authenticated, the token is saved to your system keyring — you're all set

Key details:

• Credentials are entered in your browser only — never through Claude Desktop
• Token stored in the OS keyring — persists across restarts, lasts weeks/months
• Expired sessions re-authenticate automatically — the browser login re-triggers on the next tool call
• MFA fully supported
• Fallback: run python login_setup.py in a terminal for headless environments

For technical details on the auth architecture, see docs/authentication.md.

Usage Examples

Show me all my financial accounts

What were my last 50 transactions?

How's my budget looking this month?

Analyze my cashflow for the last 3 months

Create a tag called "Business Expenses" in red

Available Tools

Tool	Description	Mode
Auth
setup_authentication	Get setup instructions	read
check_auth_status	Check authentication status	read
debug_session_loading	Debug keyring issues	read
Accounts
get_accounts	Get all financial accounts	read
get_account_holdings	Get investment holdings	read
get_account_history	Get historical balance data	read
get_recent_account_balances	Get daily balances	read
get_account_snapshots_by_type	Net worth by account type	read
get_aggregate_snapshots	Daily aggregate net value	read
get_institutions	Get connected institutions	read
get_account_type_options	Get valid account types	read
refresh_accounts	Request account data refresh	read
create_manual_account	Create manual account	write
update_account	Update account settings	write
delete_account	Delete an account	write
Transactions
get_transactions	Get transactions with filtering (date, account, category, tag, search, needs_review, and more)	read
get_transaction_details	Get full transaction detail	read
get_transactions_summary	Aggregate transaction stats	read
get_transaction_splits	Get split information	read
get_recurring_transactions	Get recurring transactions	read
find_merchant_id_by_name	Search recent transactions for a merchant and return distinct IDs	read
create_transaction	Create new transaction	write
update_transaction	Update existing transaction (clear notes with clear_notes, unlink goal with clear_goal)	write
delete_transaction	Delete a transaction	write
update_transaction_splits	Create/modify/delete splits	write
update_recurring_merchant	Mark/unmark a merchant as recurring, update its frequency/amount, or deactivate it — is_recurring is required on every call (requires --enable-write)	write
Tags
get_transaction_tags	Get all tags	read
create_transaction_tag	Create new tag	write
delete_transaction_tag	Delete a tag	write
set_transaction_tags	Set tags on a transaction	write
Categories
get_transaction_categories	Get all categories	read
get_transaction_category_groups	Get category groups	read
create_transaction_category	Create a category	write
delete_transaction_category	Delete a category	write
Rules
get_transaction_rules	List every transaction rule with its criteria, actions, and recent application stats	read
create_transaction_rule	Create a transaction rule with full criteria + actions (category, tags, merchant, amount, splits…)	write
update_transaction_rule	Update a rule by id; merges overrides onto the current rule (handles Monarch's REPLACE semantics)	write
delete_transaction_rule	Delete a rule by ID	write
Budgets & Cashflow
get_budgets	Get budget information	read
get_cashflow	Get cashflow analysis	read
get_cashflow_summary	Get cashflow summary	read
set_budget_amount	Set budget for category	write
Other
get_subscription_details	Get subscription status	read
get_credit_history	Get credit score history	read

Testing

This project has two complementary test surfaces:

1. Mocked unit tests (the quality gate) — fast, offline, no Monarch connection. These run in CI and must stay green:

uv run pytest tests/

The Monarch client is mocked, so these never touch a real account. Live e2e tests (below) are deselected by default.

2. Live end-to-end (e2e) integration tests — exercise the MCP tools against a real Monarch account to verify they handle the live API robustly (adversarial/edge inputs, server-side error paths). They are opt-in and never run in CI:

MONARCH_LIVE_TESTS=1 uv run pytest tests/integration -m integration

Prerequisites: a stored keyring token (run python login_setup.py once), or MONARCH_EMAIL / MONARCH_PASSWORD in the environment. Without these, the suite skips. The tests create and delete data prefixed with MCP-Test- and self-clean (a post-suite sweep removes any residue). See tests/integration/README.md for details and safety notes.

There is also a separate agent test skill (.claude/skills/test-monarch-mcp/) that drives an AI agent to verify it calls the tools correctly — distinct from the two pytest suites above.

🙏 Acknowledgments

Forked from @robcerda's monarch-mcp-server, maintained by vargahis.

Built on the monarchmoneycommunity Python library.

Thanks to:

• @robcerda for the original MCP server
• @hammem for the original monarchmoney library
• @bradleyseanf for the community fork

License

MIT License