{
  "markdown": "# Monarch Money MCP Server\n<!-- mcp-name: io.github.vargahis/monarch-money -->\n\nA Model Context Protocol (MCP) server for integrating with the Monarch Money personal finance platform through Claude Desktop.\n\n## Overview\n\n- **Secure by design** — browser-based login, token stored in OS keychain (never in config files or env vars)\n- **Safe by default** — read-only mode prevents accidental changes; write tools require explicit opt-in\n- **Comprehensive** — 44 tools covering accounts, transactions, splits, budgets, cashflow, tags, categories, transaction rules, recurring merchants, and credit history\n- **Easy to install** — Claude Desktop extension (`.mcpb`), `uvx`, or `pip`\n\n**Two operating modes:**\n\nThe server starts in **read-only mode** by default. Write tools are hidden and blocked until you explicitly opt in.\n\n| | Read-only (default) | Write mode |\n|---|---|---|\n| **View** accounts, transactions, budgets | Yes | Yes |\n| **Analyze** cashflow, spending, net worth | Yes | Yes |\n| **Create** transactions, tags, categories, rules | No | Yes |\n| **Update** accounts, budgets, splits | No | Yes |\n| **Delete** transactions, tags, accounts | No | Yes |\n\n## Quick Start\n\n### Installation\n\n#### Option 1: Claude Desktop Extension (.mcpb) — Recommended for Claude Desktop\n\n> Enables toggling write mode on/off directly from the Claude Desktop app.\n\n1. Download the latest `.mcpb` from [Releases](https://github.com/vargahis/monarch-mcp/releases)\n2. In Claude Desktop: **Settings > Extensions > Advanced Settings > Install Extensions** — select the `.mcpb` file\n3. Restart Claude Desktop\n\nTo enable write tools: **Settings > Extensions > Monarch Money MCP Server > Configure** — toggle **\"Enable write tools\"** and click **Save**.\n\n---\n\n#### Option 2: uvx (no install required) — Recommended for agents (e.g. Claude Code or Cursor)\n\n> Also works with Claude Desktop, but write mode cannot be toggled from the app — set it in the config instead.\n\nAdd to your MCP config file:\n\n```json\n{\n  \"mcpServers\": {\n    \"Monarch Money\": {\n      \"command\": \"uvx\",\n      \"args\": [\"monarch-mcp\"]\n    }\n  }\n}\n```\n\nTo enable write tools:\n\n```json\n{\n  \"mcpServers\": {\n    \"Monarch Money\": {\n      \"command\": \"uvx\",\n      \"args\": [\"monarch-mcp\", \"--enable-write\"]\n    }\n  }\n}\n```\n\n---\n\n#### Option 3: pip install — Recommended for local installation and venv\n\n```bash\npip install monarch-mcp\n```\n\n> **Contributors**: See [docs/releasing.md](docs/releasing.md) for the release process, version scheme, and pre-release testing via TestPyPI.\n\nAdd to your MCP config using the full path to your Python interpreter:\n\n```json\n{\n  \"mcpServers\": {\n    \"Monarch Money\": {\n      \"command\": \"/path/to/bin/python3\",\n      \"args\": [\"-m\", \"monarch_mcp\"]\n    }\n  }\n}\n```\n\nTo enable write tools, add `\"--enable-write\"` to `args`.\n\n---\n\n#### Option 4: Clone and install — Recommended for development\n\n```bash\ngit clone https://github.com/vargahis/monarch-mcp.git\ncd monarch-mcp\npip install -e .\n```\n\nThen add to your MCP config using the Python interpreter from your dev environment:\n\n```json\n{\n  \"mcpServers\": {\n    \"Monarch Money\": {\n      \"command\": \"/path/to/bin/python3\",\n      \"args\": [\"-m\", \"monarch_mcp\"]\n    }\n  }\n}\n```\n\nTo enable write tools, add `\"--enable-write\"` to `args`.\n\n### Authentication\n\nAuthentication happens **automatically in your browser** the first time the MCP server starts without a saved session.\n\n1. Start (or restart) Claude Desktop\n2. The server detects that no token exists and opens a login page in your browser\n3. Enter your Monarch Money email and password\n4. Provide your 2FA code if you have MFA enabled\n5. Once authenticated, the token is saved to your system keyring — you're all set\n\nKey details:\n\n- **Credentials are entered in your browser only** — never through Claude Desktop\n- **Token stored in the OS keyring** — persists across restarts, lasts weeks/months\n- **Expired sessions re-authenticate automatically** — the browser login re-triggers on the next tool call\n- **MFA fully supported**\n- **Fallback**: run `python login_setup.py` in a terminal for headless environments\n\nFor technical details on the auth architecture, see [docs/authentication.md](docs/authentication.md).\n\n### Usage Examples\n\n```\nShow me all my financial accounts\n```\n\n```\nWhat were my last 50 transactions?\n```\n\n```\nHow's my budget looking this month?\n```\n\n```\nAnalyze my cashflow for the last 3 months\n```\n\n```\nCreate a tag called \"Business Expenses\" in red\n```\n\n## Available Tools\n\n| Tool | Description | Mode |\n|------|-------------|------|\n| **Auth** | | |\n| `setup_authentication` | Get setup instructions | read |\n| `check_auth_status` | Check authentication status | read |\n| `debug_session_loading` | Debug keyring issues | read |\n| **Accounts** | | |\n| `get_accounts` | Get all financial accounts | read |\n| `get_account_holdings` | Get investment holdings | read |\n| `get_account_history` | Get historical balance data | read |\n| `get_recent_account_balances` | Get daily balances | read |\n| `get_account_snapshots_by_type` | Net worth by account type | read |\n| `get_aggregate_snapshots` | Daily aggregate net value | read |\n| `get_institutions` | Get connected institutions | read |\n| `get_account_type_options` | Get valid account types | read |\n| `refresh_accounts` | Request account data refresh | read |\n| `create_manual_account` | Create manual account | write |\n| `update_account` | Update account settings | write |\n| `delete_account` | Delete an account | write |\n| **Transactions** | | |\n| `get_transactions` | Get transactions with filtering (date, account, category, tag, search, needs\\_review, and more) | read |\n| `get_transaction_details` | Get full transaction detail | read |\n| `get_transactions_summary` | Aggregate transaction stats | read |\n| `get_transaction_splits` | Get split information | read |\n| `get_recurring_transactions` | Get recurring transactions | read |\n| `find_merchant_id_by_name` | Search recent transactions for a merchant and return distinct IDs | read |\n| `create_transaction` | Create new transaction | write |\n| `update_transaction` | Update existing transaction (clear notes with `clear_notes`, unlink goal with `clear_goal`) | write |\n| `delete_transaction` | Delete a transaction | write |\n| `update_transaction_splits` | Create/modify/delete splits | write |\n| `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 |\n| **Tags** | | |\n| `get_transaction_tags` | Get all tags | read |\n| `create_transaction_tag` | Create new tag | write |\n| `delete_transaction_tag` | Delete a tag | write |\n| `set_transaction_tags` | Set tags on a transaction | write |\n| **Categories** | | |\n| `get_transaction_categories` | Get all categories | read |\n| `get_transaction_category_groups` | Get category groups | read |\n| `create_transaction_category` | Create a category | write |\n| `delete_transaction_category` | Delete a category | write |\n| **Rules** | | |\n| `get_transaction_rules` | List every transaction rule with its criteria, actions, and recent application stats | read |\n| `create_transaction_rule` | Create a transaction rule with full criteria + actions (category, tags, merchant, amount, splits…) | write |\n| `update_transaction_rule` | Update a rule by id; merges overrides onto the current rule (handles Monarch's REPLACE semantics) | write |\n| `delete_transaction_rule` | Delete a rule by ID | write |\n| **Budgets & Cashflow** | | |\n| `get_budgets` | Get budget information | read |\n| `get_cashflow` | Get cashflow analysis | read |\n| `get_cashflow_summary` | Get cashflow summary | read |\n| `set_budget_amount` | Set budget for category | write |\n| **Other** | | |\n| `get_subscription_details` | Get subscription status | read |\n| `get_credit_history` | Get credit score history | read |\n\n## Testing\n\nThis project has two complementary test surfaces:\n\n**1. Mocked unit tests (the quality gate)** — fast, offline, no Monarch connection. These run in CI\nand must stay green:\n\n```bash\nuv run pytest tests/\n```\n\nThe Monarch client is mocked, so these never touch a real account. Live e2e tests (below) are\ndeselected by default.\n\n**2. Live end-to-end (e2e) integration tests** — exercise the MCP tools against a **real** Monarch\naccount to verify they handle the live API robustly (adversarial/edge inputs, server-side error\npaths). They are opt-in and never run in CI:\n\n```bash\nMONARCH_LIVE_TESTS=1 uv run pytest tests/integration -m integration\n```\n\nPrerequisites: a stored keyring token (run `python login_setup.py` once), or `MONARCH_EMAIL` /\n`MONARCH_PASSWORD` in the environment. Without these, the suite skips. The tests create and delete\ndata prefixed with `MCP-Test-` and self-clean (a post-suite sweep removes any residue). See\n[`tests/integration/README.md`](tests/integration/README.md) for details and safety notes.\n\n> There is also a separate **agent** test skill (`.claude/skills/test-monarch-mcp/`) that drives an\n> AI agent to verify it *calls* the tools correctly — distinct from the two pytest suites above.\n\n## 🙏 Acknowledgments\n\nForked from [@robcerda](https://github.com/robcerda)'s [monarch-mcp-server](https://github.com/robcerda/monarch-mcp-server), maintained by vargahis.\n\nBuilt on the [monarchmoneycommunity](https://pypi.org/project/monarchmoneycommunity/) Python library. \n\nThanks to:\n- [@robcerda](https://github.com/robcerda) for the original MCP server\n- [@hammem](https://github.com/hammem) for the original [monarchmoney](https://github.com/hammem/monarchmoney) library\n- [@bradleyseanf](https://github.com/bradleyseanf) for the community fork\n\n## License\n\nMIT License\n",
  "bytes": 9692,
  "sha": "1c7d6cbdbf4b460d89ba6ace6ab5142dc0d25bc70941a8853a17e84f8c424894",
  "repo_slug": "vargahis/monarch-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_vargahis_monarch_money_bb3fe2b9/readme"
}