monarch-mcp2-obot

Ein Single-Tenant-MCP-Server für Monarch Money zum Selbsthosting hinter obot, Fork von erikrubstein/monarch-mcp2 (selbst kein Fork der häufiger anzutreffenden robcerda/monarch-mcp-server-Familie – es ist eine unabhängige Implementierung, die auf einem eigenen API-Client basiert, monarch-api2).

Dieser Fork existiert aus drei Gründen, die Upstream nicht abgedeckt hat:

1. Portiert auf das MCP-Python-SDK v2 (MCPServer, nicht das veraltete v1-FastMCP).

2. Ein für obot entwickelter Login-Workflow: Anmeldedaten werden einmalig als Umgebungsvariablen konfiguriert, mit optionaler TOTP-Seed-Unterstützung, sodass eine MFA-Challenge der Authenticator-App automatisch gelöst werden kann – kein Browser, kein OS-Keyring, kein manuelles Abtippen eines 6-stelligen Codes.

3. Bewusst Single-Tenant: Genau ein Monarch-Konto pro laufender Instanz. Kein Tool-Aufruf kann die Sitzung eines anderen Kontos ansprechen, selbst wenn ein Client einen senden würde – siehe unten „Single-Tenant, mit Absicht“.

Nicht mit Monarch Money verbunden, von Monarch Money weder befürwortet noch unterstützt.

Was von Upstream übernommen wurde

125 Tools in 14 Gruppen – accounts, transactions, budget, cashflow, categories, goals, household, investments, merchants, receipts, recurring, reports, tags – unverändert aus monarch-mcp2. In der Tool-Liste und den Design-Hinweisen steht, was abgedeckt ist und was bewusst nicht im Rahmen liegt (Transaktionsregeln und Automatisierung, Abläufe zur Verbindung von Anbieterkonten, Account-Admin-Randfälle).

Related MCP server: monarch-mcp

Was hier anders ist

Authentifizierung: auth_login, auth_status

Zwei neue Tools, zusätzlich zu Upstreams auth_create_session / auth_save_session / auth_load_session (die weiterhin funktionieren, für eine komplett manuelle einmalige Anmeldung):

• auth_login – keine Argumente nötig, wenn in der Umgebung des Servers MONARCH_EMAIL / MONARCH_PASSWORD (und bei Authenticator-App-MFA MONARCH_TOTP_SECRET) konfiguriert sind. Eine MFA-Challenge wird automatisch gelöst, indem der aktuelle Code aus dem Seed berechnet wird. Übergib email / password / totp_secret / mfa_code explizit, um für eine einmalige Anmeldung zu überschreiben, ohne die Serverkonfiguration anzufassen.

• auth_status – meldet, ob eine Sitzung existiert und aktuell gültig ist (standardmäßig mit einem einzigen leichten API-Aufruf), ohne jemals das Session-Token zurückzugeben.

Der Server versucht diese Anmeldung außerdem automatisch beim Start, falls Anmeldedaten konfiguriert sind – als Best-Effort und nicht fatal, sodass ein falsches Passwort oder ein ausgefallenes Netzwerk den Serverstart nicht verhindert; auth_status und auth_login bleiben für Diagnose und Wiederholung verfügbar.

TOTP-Seed: dasselbe Base32-Secret, mit dem eine Authenticator-App registriert würde (das, was du als QR-Code scannen würdest). Monarch zeigt das einmal an, wenn du Authenticator-App-MFA aktivierst – speichere es dort, sonst musst du MFA deaktivieren und wieder aktivieren, um ein neues zu bekommen. Das gilt nur, wenn die MFA-Methode deines Kontos eine Authenticator-App ist; E-Mail-Code-MFA ist auf diesem Weg nicht automatisierbar (es gibt keinen Seed, aus dem ein Code berechnet werden könnte) und braucht weiterhin einen Menschen, der über das mfa_code-Argument von auth_login einen frischen Code übermittelt.

Single-Tenant, mit Absicht

session_path ist in jeder zugrunde liegenden Funktion vorhanden (eine monarch-api2-Konvention), wird aber aus dem öffentlichen Schema jedes Tools entfernt, bevor es einem MCP-Client ausgesetzt wird – siehe tool_metadata.py. Eine Bereitstellung, ein Monarch-Konto, eine Sitzungsdatei, einmal gewählt über MONARCH_SESSION_PATH / MONARCH_CONFIG_DIR. Das ist nicht nur ein Konfigurationsstandard: Kein Tool-Aufruf kann es pro Anfrage überschreiben, konstruktionsbedingt, selbst wenn ein Client einen gesendet hätte (siehe tests/test_server.py::test_tool_call_ignores_session_path_even_if_a_client_sends_it).

Transportauswahl für obots zwei Bereitstellungsmodelle

obot unterstützt MCP-Server auf zwei hier relevanten Wegen: kommando-/uvx-basiert (stdio) und Docker-basiert (ein Port plus ein streamable-http-Endpunkt). Beide werden über MCP_TRANSPORT unterstützt (Standard stdio); das Docker-Image setzt es standardmäßig auf streamable-http. Siehe config.py / server.py.

Umgebungsvariablen

Behandle MONARCH_PASSWORD und MONARCH_TOTP_SECRET wie jedes andere Geheimnis – obots Single-User-MCP-Servermodell markiert solche Felder als „sensibel“, wenn ein Admin den Server konfiguriert; nutze das.

Ausführen

obot, kommando-/uvx-basiert (stdio)

uvx --from git+https://<your-fork-url> monarch-mcp

(Sobald du diesen Fork irgendwohin gepusht hast – siehe die Anmerkung am Ende dieser README dazu, wo dieser Code derzeit liegt.)

obot, Docker-basiert (streamable-http)

docker build -t monarch-mcp2-obot:local .
docker volume create monarch-session

docker run -d --rm \
  -p 8000:8000 \
  -v monarch-session:/data \
  -e MONARCH_EMAIL=you@example.com \
  -e MONARCH_PASSWORD=... \
  -e MONARCH_TOTP_SECRET=...  `# omit if your account doesn't use authenticator-app MFA` \
  monarch-mcp2-obot:local

Richte obots Docker-basierte MCP-Server-Konfiguration auf den streamable-http-Endpunkt dieses Containers auf Port 8000 aus. Der Sitzungszustand liegt im Volume monarch-session und übersteht so Container-Neustarts und erneute Deployments ohne erneute Anmeldung.

Lokale Entwicklung (stdio, ohne Docker)

uv sync
uv run monarch-mcp

Testen

uv run pytest
uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy src/monarch_mcp/auth_runtime.py src/monarch_mcp/config.py \
  src/monarch_mcp/server.py src/monarch_mcp/groups/auth.py src/monarch_mcp/tool_metadata.py

(mypy --strict ist auf die Dateien beschränkt, die dieser Fork erstellt oder wesentlich verändert hat; die übernommenen Gruppenmodule wurden im Rahmen dieses Forks nicht erneut auf strikte Typisierung geprüft – siehe ROADMAP.md.)

Wo dieser Code liegt

Dies wurde lokal erstellt und verifiziert (installiert, getestet und ausgeführt – mit beiden Transporten – gegen einen echten MCP-initialize-Handshake), aber im Rahmen dieser Arbeit nicht in ein gehostetes Git-Remote gepusht. Pushe den Code in deinen eigenen Fork bzw. dein eigenes Remote, bevor du uvx --from git+... darauf richtest, und aktualisiere die Docker-Build-Anweisungen oben entsprechend, wenn du von diesem Remote statt aus einem lokalen Checkout baust.

Lizenz

MIT, von Upstream übernommen. Siehe LICENSE.