monarch-mcp2-obot

Un servidor MCP de Monarch Money de un solo inquilino para autoalojar detrás de obot, un fork de erikrubstein/monarch-mcp2 (que a su vez no es un fork de la familia robcerda/monarch-mcp-server, más comúnmente vista — es una implementación independiente respaldada por su propio cliente de API, monarch-api2).

Este fork existe por tres razones que el proyecto original no cubría:

1. Portado a MCP Python SDK v2 (MCPServer, no la obsoleta v1 FastMCP).

2. Un flujo de inicio de sesión diseñado para obot: las credenciales se configuran una vez como variables de entorno, con soporte opcional de semilla TOTP para que un desafío de MFA de aplicación de autenticador pueda resolverse automáticamente — sin navegador, sin llavero del sistema operativo, sin copiar un código de 6 dígitos a mano.

3. Deliberadamente de un solo inquilino: exactamente una cuenta de Monarch por instancia en ejecución. Ninguna llamada a herramienta puede apuntar a la sesión de otra cuenta, aunque un cliente intente enviarla — ver «De un solo inquilino, a propósito» más abajo.

No afiliado a Monarch Money, ni respaldado ni soportado por Monarch Money.

Qué se hereda de upstream

125 herramientas en 14 grupos — accounts, transactions, budget, cashflow, categories, goals, household, investments, merchants, receipts, recurring, reports, tags — sin cambios respecto a monarch-mcp2. Consulta su lista de herramientas y notas de diseño para saber qué se cubre y qué queda deliberadamente fuera del alcance (reglas de transacciones y automatización, flujos de conexión de cuentas de proveedores, aspectos de administración de cuentas).

Related MCP server: monarch-mcp

Qué cambia aquí

Autenticación: auth_login, auth_status

Dos herramientas nuevas, además de auth_create_session / auth_save_session / auth_load_session del proyecto upstream (que siguen funcionando para un inicio de sesión completamente manual de una sola vez):

• auth_login — no necesita argumentos si el entorno del servidor tiene configurados MONARCH_EMAIL / MONARCH_PASSWORD (y, para MFA de aplicación de autenticador, MONARCH_TOTP_SECRET). Resuelve automáticamente un desafío de MFA calculando el código actual a partir de la semilla. Pasa email / password / totp_secret / mfa_code explícitamente para anular la configuración en un inicio de sesión puntual sin tocar la configuración del servidor.

• auth_status — informa de si existe una sesión y si es válida actualmente (una llamada ligera a la API por defecto), sin devolver nunca el token de sesión.

El servidor también intenta este inicio de sesión automáticamente al arrancar si hay credenciales configuradas — con un enfoque de mejor esfuerzo y no bloqueante, de modo que una contraseña incorrecta o una red caída no impidan que el servidor se inicie; auth_status y auth_login siguen disponibles para diagnosticar y reintentar.

Semilla TOTP: el mismo secreto base32 con el que se inscribiría una aplicación de autenticador (lo que escanearías como código QR). Monarch lo muestra una sola vez al activar la MFA de aplicación de autenticador — guárdalo en ese momento, o tendrás que desactivar y reactivar la MFA para obtener uno nuevo. Esto solo aplica si el método de MFA de tu cuenta es una aplicación de autenticador; la MFA por código de correo no se puede automatizar de esta manera (no hay semilla de la que calcular un código) y aún necesita que una persona facilite un código nuevo mediante el argumento mfa_code de auth_login.

De un solo inquilino, a propósito

session_path existe en todas las funciones subyacentes (una convención de monarch-api2), pero se elimina del esquema público de todas las herramientas antes de exponerse a un cliente MCP — ver tool_metadata.py. Un despliegue, una cuenta de Monarch, un archivo de sesión, elegidos una vez mediante MONARCH_SESSION_PATH / MONARCH_CONFIG_DIR. Esto no es solo un valor predeterminado de configuración: por diseño, ninguna llamada a herramienta puede sobrescribirlo por solicitud, aunque un cliente envíe una de todos modos (ver tests/test_server.py::test_tool_call_ignores_session_path_even_if_a_client_sends_it).

Selección de transporte para los dos modelos de despliegue de obot

obot admite servidores MCP de dos maneras relevantes aquí: basado en comando/uvx (stdio) y basado en Docker (un puerto más un endpoint streamable-http). Ambos se configuran mediante MCP_TRANSPORT (por defecto stdio); la imagen de Docker lo establece en streamable-http por defecto. Ver config.py / server.py.

Variables de entorno

Trata MONARCH_PASSWORD y MONARCH_TOTP_SECRET como cualquier otro secreto: el modelo de servidor MCP de un solo usuario de obot marca campos como estos como «sensitive» cuando un administrador configura el servidor; aprovéchalo.

Cómo ejecutarlo

obot, basado en comando/uvx (stdio)

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

(Una vez que hayas subido este fork a algún sitio — ver la nota al final de este README sobre dónde vive actualmente este código.)

obot, basado en Docker (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

Apunta la configuración del servidor MCP basado en Docker de obot al endpoint streamable-http de este contenedor en el puerto 8000. El estado de la sesión vive en el volumen monarch-session, por lo que sobrevive a reinicios del contenedor y redespliegues sin necesidad de volver a iniciar sesión.

Desarrollo local (stdio, sin Docker)

uv sync
uv run monarch-mcp

Pruebas

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 está limitado a los archivos que este fork creó o cambió sustancialmente; los módulos de grupo heredados no fueron reauditados para tipado estricto como parte de este fork — ver ROADMAP.md.)

Dónde vive este código

Esto se construyó y verificó localmente (instalado, probado y ejecutado — ambos transportes — contra un handshake initialize real de MCP), pero no se ha subido a un remoto git alojado como parte de este trabajo. Súbelo a tu propio fork/remoto antes de apuntar uvx --from git+... hacia él, y actualiza las instrucciones de construcción de Docker anteriores en consecuencia si compilas desde ese remoto en lugar de desde un checkout local.

Licencia

MIT, heredada del proyecto upstream. Ver LICENSE.