amazing-marvin-complete-mcp

Un servidor MCP (Model Context Protocol) para Amazing Marvin con cobertura completa de la API pública: 34 herramientas sobre los ~31 endpoints documentados, un limitador de tasa global que respeta los límites documentados de Marvin, enrutamiento de tokens con privilegios mínimos y anotaciones de herramientas MCP. Cada afirmación de comportamiento no obvia en las descripciones de las herramientas se verificó contra la API en vivo; los hallazgos se documentan a continuación en Particularidades y hallazgos de la API de Marvin, que pueden ser útiles incluso si nunca ejecutas este servidor.

Se proporciona tal cual. Este proyecto no se mantiene activamente y no incluye soporte. Las incidencias están desactivadas a propósito. Haz fork libremente: es MIT.

Herramientas (34)

Deliberadamente no incluidas: la lógica de Smart List / selección de tareas. El propio Spotlight de Marvin hace la selección; el servidor le da manos a tu asistente, no opiniones.

Cada herramienta lleva anotaciones de herramientas MCP (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) para que los clientes capaces traten delete_task y reset_reward_points con el respeto que merecen.

Related MCP server: Super-Productivity-MCP

Cómo obtener tus tokens de Marvin

Ambos tokens viven en Amazing Marvin en Settings → API (app.amazingmarvin.com/pre?api):

• API Token (MARVIN_API_TOKEN, obligatorio): acceso limitado; suficiente para leer y crear tareas.

• Full Access Token (MARVIN_FULL_ACCESS_TOKEN, opcional pero recomendado): lo requieren todas las herramientas basadas en /doc*: update_task, set_priority, unmark_done, delete_task, creación de categorías, bloques de tiempo, list_habits, recordatorios, reset_reward_points.

Trátalos como contraseñas; consulta SECURITY.md.

Instalación y ejecución

Requiere Python 3.12+.

git clone <this repo> && cd amazing-marvin-complete-mcp
python -m venv .venv && .venv/bin/pip install .

Local (stdio): Claude Desktop, Claude Code, cualquier cliente MCP

El transporte predeterminado es stdio, por lo que el cliente inicia el servidor por sí mismo:

{
  "mcpServers": {
    "amazing-marvin": {
      "command": "/path/to/.venv/bin/marvin-mcp",
      "env": {
        "MARVIN_API_TOKEN": "…",
        "MARVIN_FULL_ACCESS_TOKEN": "…",
        "MARVIN_TIMEZONE": "Europe/Stockholm"
      }
    }
  }
}

(Para Claude Code: claude mcp add amazing-marvin -e MARVIN_API_TOKEN=… -- /path/to/.venv/bin/marvin-mcp).

Remoto (Streamable HTTP)

MCP_TRANSPORT=http PORT=8787 MCP_AUTH_TOKEN_FILE=/path/to/token \
MARVIN_API_TOKEN_FILE=/path/to/api-token .venv/bin/marvin-mcp

El endpoint MCP es /mcp. La verificación de bearer integrada (MCP_AUTH_TOKEN) protege todas las rutas, pero es una barrera interna, no una solución de autenticación completa: coloca un proxy inverso con TLS delante y, para conectores personalizados de Claude, un proxy de autenticación MCP compatible con OAuth 2.1. Se incluye un Dockerfile para el modo HTTP (se ejecuta como usuario no root; monta un volumen en /data para conservar el contador diario de límite de tasa entre reinicios).

Configuración

Todos los ajustes mediante variables de entorno; consulta .env.example para la lista completa anotada. Lo más destacado: cada secreto admite una variante *_FILE (recomendada); MARVIN_TIMEZONE debe coincidir con la zona horaria en la que vive tu cuenta de Marvin (por defecto usa la zona horaria del sistema, que es UTC en la mayoría de los contenedores).

Límite de tasa

Los límites documentados de Marvin (1 escritura/segundo, 1 lectura/3 segundos, 1440 llamadas/día) se aplican mediante una única cola global del proceso compartida por todas las herramientas y sesiones, con margen (1,1 s / 3,1 s). El contador diario persiste entre reinicios (STATE_DIR) y se reinicia a medianoche en la zona horaria configurada. get_rate_limit_status muestra el uso de hoy.

Particularidades y hallazgos de la API de Marvin

Todo lo siguiente se verificó contra la API en vivo el 2026-08-19. Esta es la mitad del repositorio que puedes usar sin ejecutarlo.

Hábitos

• GET /habits sin raw no lee tus documentos de hábitos. Lee un registro de seguimiento del lado del servidor que se crea de forma perezosa en el primer registro: un hábito que nunca se ha registrado falta por completo en la respuesta, y las entradas no llevan títulos (solo habitId + historial). Usa ?raw=1 (Full Access Token) para listar los documentos de hábitos reales. GET /habit?id=… devuelve el registro de seguimiento: historial pero sin título.

• POST /updateHabit rechaza enteros serializados como flotantes: "value": 1.0 → 400 Bad request, "value": 1 → 200. Envía los enteros como enteros.

Tareas y proyectos

• POST /markDone funciona solo para tareas: los proyectos devuelven 400 "Can only mark Tasks done with this API".

• /addTask analiza la sintaxis de acceso rápido de Marvin en el servidor: ~15 se convierte en un timeEstimate de 15 minutos y +YYYY-MM-DD establece day (programación, no la fecha límite). Ambos se eliminan del título. Pero nunca uses #Category a través de la API: el servidor almacena la cadena literalmente como parentId (codicioso hasta el primer guion, p. ej. #MCP-TEST → parentId: "#MCP" y un título corrupto) sin resolver ningún ID. La tarea entonces vive fuera de toda categoría y fuera de la Bandeja de entrada, efectivamente invisible. (Reportado por primera vez por lucasoeth/marvin-mcp; reproducido de forma independiente aquí).

• Las instancias generadas de tareas recurrentes tienen IDs deterministas (YYYY-MM-DD_<recurringTaskId>), por lo que marcarlas como hechas/deshechas a través de la API no puede crear duplicados. Las instancias las genera el cliente de Marvin, por lo que las tareas recurrentes de hoy pueden faltar en /todayItems hasta que la aplicación haya estado en ejecución.

• /doc/update puede devolver esporádicamente un 500 transitorio; la escritura es atómica (sin estado parcial): solo reintenta. Los cambios de nombre de proyectos, movimientos, cambios de etiquetas, etc. funcionan a través de él.

• /doc/create no devuelve un _id generado por el servidor: proporciona el tuyo propio si necesitas referenciar el documento después.

• La eliminación mediante /doc/delete es permanente; la papelera de Marvin es del lado del cliente.

Puntos de recompensa y kudos

• Los kudos (XP/nivel, se leen mediante /kudos) y los puntos de recompensa (reclamar/desreclamar/gastar/reiniciar) son dos sistemas separados. /kudos carece de nextMultiplier (problema #5 de MarvinAPI): está en /me.

• /markDone no otorga los puntos de recompensa de una tarea (cf. problema #6 para kudos): claimRewardPoints es una llamada separada.

• Una reclamación MANUAL (itemId: "MANUAL") no se puede deshacer: el servidor no almacena ninguna entrada para ella, por lo que /unclaimRewardPoints devuelve 404 "No such entry" (con o sin un campo points), y reclamar puntos negativos se rechaza con 400. La aplicación web de Marvin nunca usa MANUAL: es una funcionalidad exclusiva de la API. La única compensación es gastar la misma cantidad, lo que infla las estadísticas de gasto.

• /spendRewardPoints devuelve un 500 si el saldo quedaría negativo.

Recordatorios

• Un recordatorio de tarea en Marvin son dos escrituras que solo la aplicación mantiene sincronizadas: los campos de recordatorio en el documento de la tarea (taskTime, reminderTime, reminderOffset, snooze, autoSnooze) y una entrada del lado del servidor mediante /reminder/set. Escribir solo un lado (todo lo que la API te permite hacer cómodamente) produce entradas que la interfaz de la aplicación no mostrará en la tarea, o huérfanos del lado del servidor. Los recordatorios independientes (tipo M) son el uso seguro de la API. (Riesgo documentado por primera vez por Recon2026/marvin-mcp; confirmado por la propia advertencia de la wiki oficial).

Tiempo y planificación

• /todayTimeBlocks omite el vínculo bloque↔categoría (problema #65); este servidor recupera la asignación del documento de perfil strategySettings.plannerSmartLists.

• Detener el registro de tiempo mediante la API no actualiza los campos times/duration de la propia tarea; /tracks es la fuente de verdad.

• Los eventos de calendario creados mediante /addEvent se sincronizan hacia adelante solo mientras la aplicación de Marvin se está ejecutando en algún lugar (sincronización de calendario del lado del cliente).

En qué se diferencia de las alternativas existentes

Existen varios servidores MCP buenos de Amazing Marvin; este se construyó desde cero (sin código compartido) después de estudiarlos, con un objetivo diferente: cobertura completa de la API pública en lugar de un subconjunto seleccionado:

• bgheneti/Amazing-Marvin-MCP — el servidor Python establecido; cobertura amplia pero no completa, sin limitación de tasa global.

• Recon2026/marvin-mcp — alcance más reducido (19 herramientas), investigación inusualmente cuidadosa; optó por hacer los recordatorios de solo lectura ante el riesgo de doble escritura. Este servidor incluye escrituras de recordatorios con advertencias explícitas en su lugar.

• lucasoeth/marvin-mcp — una filosofía diferente: un puñado de herramientas de flujo de trabajo consolidadas (brief/capture/…) en lugar de un espejo de la API, además de lecturas directas de CouchDB para búsqueda y tareas completadas (que la API pública no puede hacer en absoluto). Si quieres flujos de trabajo con opiniones o búsqueda, usa el suyo; si quieres acceso completo y sin filtrar a la API con los bordes afilados documentados, usa este.

• LucaDeLeo/amazing-marvin-mcp — un subconjunto de API limitada.

Créditos y fuentes

No se copió código de ninguno de estos: la construcción es nueva, pero influyeron de forma sustancial en ella:

• amazingmarvin/MarvinAPI (+ wiki): la documentación oficial de la API, la especificación OpenAPI, los tipos de datos y el rastreador de incidencias contra los que se construyó este servidor.

• bgheneti/Amazing-Marvin-MCP — inspiración de arquitectura, referencia de endpoints durante el análisis inicial de brechas y el precedente de la licencia MIT.

• Recon2026/marvin-mcp — el riesgo de integridad de doble escritura en los recordatorios y el trabajo preliminar sobre las instancias de tareas recurrentes, ambos verificados y documentados aquí.

• lucasoeth/marvin-mcp — el error del acceso rápido #Category (reproducido aquí) y la idea de que la base de datos de sincronización de Marvin es un CouchDB real utilizable para lecturas.

• LucaDeLeo/amazing-marvin-mcp — la indicación de que /addTask analiza la sintaxis de acceso rápido en el servidor (confirmada en parte, refutada en parte; consulta el hallazgo de #Category), y la idea de las anotaciones de herramientas MCP.

Construido con Claude Code (Claude Fable 5).

Licencia

MIT.