Skip to content

monarch-mcp2-obot

A single-tenant Monarch Money MCP server for self-hosting behind obot, forked from erikrubstein/monarch-mcp2 (itself not a fork of the more commonly-seen robcerda/monarch-mcp-server family — it's an independent implementation backed by its own API client, monarch-api2).

Not affiliated with, endorsed by, or supported by Monarch Money.

Why this fork exists

  1. Ported to MCP Python SDK v2 (MCPServer, not the deprecated v1 FastMCP).
  2. A login workflow built for obot: credentials configured once as environment variables, with optional TOTP-seed support so an authenticator-app MFA challenge can be solved automatically — no browser, no OS keyring, no copying a 6-digit code by hand. See Authentication.
  3. Deliberately single-tenant: exactly one Monarch account per running instance. No tool call can target a different account's session, even if a client tried to send one.
  4. Resilient to session expiry: tool calls that fail because the saved session expired are transparently retried once after a fresh login, instead of surfacing a raw 401 to the caller — see Authentication.

What's inherited from upstream

125 tools across 14 groups — accounts, transactions, budget, cashflow, categories, goals, household, investments, merchants, receipts, recurring, reports, tags — unchanged from monarch-mcp2. See its tool list and design notes for what's covered and what's deliberately out of scope (transaction rules and automation, provider account-connection flows, account-admin edges). See Tools for how those tools are shaped and controlled from an MCP client.

Where to go next

  • Installation — obot (uvx/stdio and Docker), local development.
  • Configuration — every environment variable, transport selection, secrets management.
  • Authentication — auth_login/auth_status, TOTP MFA, the reauth-on-expiry retry.
  • Tools — the 125+ tools, output shaping (output_mode/fields), the single-tenant guarantee.
  • Development — running tests/lint/type-checks, pre-commit, contributing.

License

MIT, inherited from upstream. See LICENSE and NOTICE for the full attribution chain.