amazing-marvin-mcp

Resumen

Un servidor MCP no oficial para Amazing Marvin, para que un asistente como Claude pueda responder «¿qué hay en mi bandeja de entrada?», «¿qué vence esta semana?», «estoy en el coche, ¿qué puedo hacer?», y actuar en consecuencia: renombrar, reetiquetar, reprogramar, mover, dividir en proyectos, guardar investigación en una nota.

Este proyecto no está afiliado, respaldado ni soportado por Amazing Marvin; utiliza su API pública.

Cómo funciona

Claude ──MCP (stdio)──▶ amazing-marvin-mcp
                          ├─ local mirror ◀── CouchDB `_changes` (your sync database)
                          │    reads, search and filters run here: no rate-limit cost
                          └─ writes ──▶ Marvin REST API (addTask, doc/update, markDone)
                                        throttled to Marvin's limits (1 request / 3 s)

La API REST de Marvin no tiene un endpoint de «listar» ni de «buscar» y tiene un presupuesto de 1440 solicitudes por día, por lo que las lecturas provienen de una copia local de tu base de datos mantenida al día con una consulta incremental de _changes (como máximo una vez por minuto). Las escrituras pasan por la API REST, que maneja la contabilidad de resolución de conflictos de Marvin (fieldUpdates) en el servidor.

Lo que sabe el asistente

• Semántica de Marvin, en las propias palabras de la interfaz. Bandeja de entrada = no archivado en ningún sitio; las categorías y proyectos se anidan arbitrariamente (la Lista Maestra). Las cuatro fechas se mantienen separadas: Fecha de hacer (el día en que planeas hacerlo, «programado»), Fecha de vencimiento (plazo externo duro), Fecha de fin (objetivo autoimpuesto; la semana/mes planificado de Planning Ahead es la forma más suave), Fecha de inicio (oculta en Backburner hasta entonces). Además, estimaciones de duración (minutos), importancia (estrellas P1–P3), Eat-the-Frog, Backburner, etiquetas y grupos de etiquetas.

• Tu estructura (get_structure): el árbol de categorías/proyectos con ids y recuentos de tareas abiertas, etiquetas por grupo, y qué estrategias de Marvin tienes habilitadas (por sus nombres en la pantalla de Estrategias).

• Tu flujo de trabajo (workflow.md o un directorio workflow/ de secciones): cómo tú usas Marvin: qué significan las etiquetas, cómo planificas, tu lista de verificación de triaje de la bandeja de entrada, qué significa «victoria rápida». Marvin es flexible, así que esto es lo que permite al asistente actuar como lo harías tú. Se inyecta en las instrucciones del servidor y se expone como marvin://workflow (y marvin://workflow/<sección>).

Herramientas

Deliberadamente no hay herramienta de eliminación: la papelera de Marvin es del lado del cliente, por lo que las eliminaciones por API son irrecuperables.

Related MCP server: Amazing Marvin MCP

Instalación y configuración (para usarlo)

1. Instala (necesita uv):

   uv tool install git+https://github.com/tsvikas/amazing-marvin-mcp.git

2. Credenciales. En Marvin, activa la estrategia API (Estrategias → API → ajustes). Pon sus valores en ~/.config/amazing-marvin-mcp/.env (Linux; amazing-marvin-mcp check imprime la ruta exacta en tu sistema operativo):

   MARVIN_API_TOKEN=...           # create / mark done
   MARVIN_FULL_ACCESS_TOKEN=...   # edit existing items; omit for no edits
   MARVIN_SYNC_SERVER=...         # CouchDB: the read mirror
   MARVIN_SYNC_DATABASE=...
   MARVIN_SYNC_USER=...
   MARVIN_SYNC_PASSWORD=...

   Las variables de entorno y un .env en el directorio de trabajo también funcionan (y anulan el archivo por usuario). Mientras pruebas, usa una segunda cuenta de Marvin desechable: el token de acceso completo puede dañar datos.

3. Comprueba y primera sincronización:

   amazing-marvin-mcp check     # verifies tokens, pulls the database, prints counts

4. Describe tu flujo de trabajo:

   amazing-marvin-mcp init-workflow            # one workflow.md to edit, or
   amazing-marvin-mcp init-workflow --split    # a workflow/ directory: planning, labels, triage, daily…

   Todo lo que contenga va a las instrucciones del modelo (y cada sección es también un recurso marvin://workflow/<sección>), así que mantenlo breve y concreto.

5. Regístrate con tu cliente MCP.

   Claude Code:

   claude mcp add marvin -- amazing-marvin-mcp serve

   Claude Desktop (claude_desktop_config.json):

   {
     "mcpServers": {
       "marvin": { "command": "amazing-marvin-mcp", "args": ["serve"] }
     }
   }

   Ambos leen el .env por usuario, así que no van secretos en la configuración del cliente. Luego pregunta: «¿qué hay en mi bandeja de entrada de Marvin?»

Otros ajustes (mostrados por check): MARVIN_WORKFLOW_FILE (archivo o directorio), MARVIN_CACHE_DIR, MARVIN_MIN_REQUEST_INTERVAL (segundos entre llamadas REST, por defecto 3), MARVIN_MIRROR_MAX_AGE (segundos antes de que una lectura vuelva a consultar, por defecto 60).

El archivo espejo contiene todas tus tareas; se escribe con permisos solo para el propietario en el directorio de caché.

Desarrollo

git clone https://github.com/tsvikas/amazing-marvin-mcp && cd amazing-marvin-mcp
uv sync && just prepare                     # deps + pre-commit hooks
just test && just lint

Ejecuta el servidor desde el checkout (un .env en la raíz del repositorio está ignorado por git y se recoge cuando el cliente se inicia desde este directorio; de lo contrario, usa -e VAR=value o el archivo por usuario):

claude mcp add marvin-dev -- uv run --directory "$PWD" amazing-marvin-mcp serve

tests/test_live.py ejecuta cada herramienta de extremo a extremo y reproduce una cassette grabada por defecto (tests/cassettes/), que también sirve como fixture de documentos reales de Marvin. Para volver a grabar contra una cuenta desechable (crea y luego elimina algunos elementos [live]):

MARVIN_API_TOKEN=... MARVIN_FULL_ACCESS_TOKEN=... MARVIN_SYNC_SERVER=... \
MARVIN_SYNC_DATABASE=... MARVIN_SYNC_USER=... MARVIN_SYNC_PASSWORD=... \
uv run pytest tests/test_live.py --record-mode=rewrite

Las reglas de diseño para contribuciones están en CLAUDE.md.

Contribuciones

¿Interesado en contribuir? Consulta CONTRIBUTING.md para la configuración de desarrollo y las pautas.