todoist-v1-mcp-server

Un servidor MCP (Model Context Protocol) limpio y fiable para Todoist, construido sobre la API unificada v1 de Todoist.

¿Por qué existe esto?

El MCP web oficial de Todoist (todoist-ai) tiene un error de desconexión persistente conocido en el lado de Anthropic que requiere reconectarse a diario. Las alternativas de la comunidad están construidas sobre la API REST v2 (ya obsoleta) o tienen errores de validación de esquema que provocan fallos cuando Todoist devuelve campos adicionales a medida que su API evoluciona.

Este servidor:

• Se dirige a la API v1 actual de Todoist (no a la v2 obsoleta)

• Utiliza transporte stdio: sin dependencia de la nube, sin reconexiones diarias

• Utiliza la API moderna registerTool() del SDK de MCP (no el patrón setRequestHandler obsoleto)

• Nunca impone esquemas de salida estrictos en las respuestas de la API: Todoist puede añadir nuevos campos libremente sin romper nada

• Cero dependencia de envoltorios de SDK: llamadas HTTP directas mediante axios, por lo que no hay ninguna biblioteca intermedia que se desvíe de la API

Herramientas (20 en total)

Tareas

Proyectos

Secciones

Etiquetas

Configuración

1. Obtén tu token de API de Todoist

Ve a Todoist → Ajustes → Integraciones → Desarrollador y copia tu token de API.

2. Instalar y compilar

git clone https://github.com/christulino/todoist-v1-mcp-server
cd todoist-v1-mcp-server
npm install
npm run build

3. Configurar Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "todoist": {
      "command": "node",
      "args": ["/absolute/path/to/todoist-v1-mcp-server/dist/index.js"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Reinicia Claude Desktop. Deberías ver "todoist" en los servidores MCP conectados.

4. Configurar Claude Code (opcional)

claude mcp add todoist -- node /absolute/path/to/todoist-v1-mcp-server/dist/index.js

Luego establece la variable de entorno:

export TODOIST_API_TOKEN=your_api_token_here

O añádela a tu perfil de shell.

Ejemplos de uso

Una vez conectado, Claude puede manejar lenguaje natural como:

• "¿Qué tengo pendiente hoy?" → utiliza todoist_get_tasks con filter: "today"

• "Añade una tarea para llamar al dentista el próximo martes" → utiliza todoist_create_task

• "Marca la tarea del dentista como hecha" → utiliza todoist_complete_task

• "Muéstrame todo lo que está vencido" → utiliza todoist_get_tasks con filter: "overdue"

• "Crea un proyecto llamado Renovación del Hogar" → utiliza todoist_create_project

• "¿Qué proyectos tengo?" → utiliza todoist_get_projects

Sintaxis de filtros de Todoist

El parámetro filter en todoist_get_tasks admite la sintaxis completa de filtros en lenguaje natural de Todoist:

Documentación completa de filtros: https://todoist.com/help/articles/introduction-to-filters

Requisitos

• Node.js 18+

• Una cuenta de Todoist (la versión gratuita funciona)

Desarrollo

npm run dev   # tsx watch mode with auto-reload
npm run build # compile TypeScript
npm start     # run compiled server

Pruebas

El conjunto de pruebas accede a la API de Todoist en vivo y ejecuta un ciclo CRUD completo a través de tareas, proyectos, secciones y etiquetas. Todos los datos de prueba tienen el prefijo [mcp-test] y se eliminan automáticamente.

TODOIST_API_TOKEN=your_token npm test

Tu token de API está en Todoist → Ajustes → Integraciones → Desarrollador: el mismo token que pusiste en claude_desktop_config.json.

Contribución

Las PR son bienvenidas. El objetivo es una implementación mínima y correcta que se mantenga al día con la API v1 de Todoist. Prioridades:

1. Corrección sobre ingenio

2. Manejo permisivo de la salida (nunca rechazar campos de API desconocidos)

3. Mensajes de error útiles que indiquen qué salió mal y cómo solucionarlo

Licencia

MIT