Todoist

Servidor MCP de Todoist

Un servidor MCP (Protocolo de Contexto de Modelo) que conecta a Claude con Todoist para la gestión completa de tareas y proyectos mediante lenguaje natural.

Instalación

Claude Desktop (Instalación en un clic)

1. Descarga todoist-mcp.mcpb desde la última versión
2. Haz doble clic en el archivo (o arrástralo a Claude Desktop)
3. Introduce tu token de API de Todoist cuando se te solicite
4. Empieza a chatear: "Muéstrame mis proyectos de Todoist"

Claude Code / Otros clientes MCP

claude mcp add todoist -e TODOIST_API_TOKEN=your_token -- npx @greirson/mcp-todoist

{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["@greirson/mcp-todoist"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Características

• 19 herramientas MCP para la gestión completa de Todoist
• Gestión de tareas: Crear, actualizar, eliminar, completar, reabrir tareas con prioridades, fechas de vencimiento, etiquetas
• Operaciones masivas: Procesa múltiples tareas de manera eficiente
• Subtareas: Gestión jerárquica de tareas con seguimiento de finalización
• Proyectos y secciones: Soporte completo de organización
• Etiquetas, filtros, recordatorios: Funciones Pro/Business compatibles
• Lenguaje natural: Añadido rápido con el análisis de lenguaje natural de Todoist
• Modo de prueba: Prueba operaciones sin realizar cambios

Modo de prueba

El modo de prueba te permite probar operaciones y automatizaciones sin realizar cambios reales en tu espacio de trabajo de Todoist. Es perfecto para probar, depurar, aprender la API o validar scripts de automatización antes de ejecutarlos de verdad.

Cómo activar el modo de prueba

Añade DRYRUN=true a tu configuración de entorno:

{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["@greirson/mcp-todoist"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here",
        "DRYRUN": "true"
      }
    }
  }
}

Qué hace el modo de prueba

• Valida operaciones: Utiliza datos reales de la API para validar que las operaciones tendrían éxito
• Simula mutaciones: Las operaciones de crear, actualizar, eliminar y completar se simulan (no se ejecutan)
• Consultas de datos reales: Las operaciones de lectura (obtener tareas, proyectos, etiquetas) utilizan la API real
• Registro detallado: Muestra exactamente qué sucedería con prefijos claros de [DRY-RUN]
• Detección de errores: Detecta los mismos errores que ocurrirían en la ejecución real

Casos de uso

• Probar automatizaciones: Valida operaciones masivas complejas antes de ejecutarlas
• Aprender la API: Explora la funcionalidad sin miedo a realizar cambios no deseados
• Depurar problemas: Comprende qué operaciones se realizarían
• Experimentación segura: Prueba nuevos flujos de trabajo sin afectar tus tareas reales
• Formación y demostraciones: Muestra cómo funcionan las operaciones sin modificar datos reales

Ejemplo de uso

Con el modo de prueba activado, las operaciones muestran qué sucedería:

You: "Create a task called 'Test Task' in my Work project"

Response:
[DRY-RUN] Dry-run mode enabled - mutations will be simulated
[DRY-RUN] Would create task: "Test Task" in project 2203306141, section none

Task created successfully (simulated):
ID: 100001
Title: Test Task
Project: Work (2203306141)
Priority: 4 (Normal)

Operaciones compatibles

Las 19 herramientas MCP admiten el modo de prueba:

• Creación, actualización, finalización y eliminación de tareas
• Operaciones de subtareas y cambios de jerarquía
• Operaciones masivas en múltiples tareas
• Creación de proyectos y secciones
• Operaciones de gestión de etiquetas
• Operaciones CRUD de recordatorios
• Creación de comentarios

Desactivar el modo de prueba

Elimina la variable de entorno DRYRUN o establécela en false, y reinicia Claude Desktop para volver al modo de operación normal.

Resumen de herramientas

El servidor proporciona 19 herramientas MCP para la gestión completa de Todoist:

Para documentación detallada de herramientas con parámetros y ejemplos, consulta TOOLS_REFERENCE.md.

Solución de problemas

Problemas comunes

"No se encontraron proyectos de Todoist" o errores de conexión:

• Verifica que tu token de API sea correcto
• Comprueba que el token esté configurado correctamente en tu claude_desktop_config.json
• Asegúrate de que no haya espacios adicionales ni comillas alrededor de tu token

El servidor MCP no se carga:

• Confirma que el paquete esté instalado globalmente: npm list -g @greirson/mcp-todoist
• Reinicia Claude Desktop por completo
• Comprueba que la ruta del archivo de configuración sea correcta para tu sistema operativo
• Prueba con la ruta completa al binario de mcp-todoist: /Users/USERNAME/.npm-global/bin/mcp-todoist

Errores de permisos:

• En macOS/Linux, es posible que necesites crear el directorio de configuración: mkdir -p ~/.config
• Asegúrate de que Claude Desktop tenga permiso para leer el archivo de configuración

Ejemplos de uso

Configuración de proyectos y secciones

"Show me all my projects"
"Create a new project called 'Work Tasks'"
"Create a section called 'In Progress' in project 12345"
"Show me sections in the Work Tasks project"

Creación y gestión de tareas

"Create task 'Team Meeting' in project 12345"
"Add task 'Review PR' due tomorrow with labels ['Code Review', 'Urgent']"
"Create high priority task with deadline 2024-12-25"
"Update meeting task to be in section 67890"
"Mark the PR review task as complete"

# Task duration for time blocking
"Create task 'Deep work session' with 90 minute duration"
"Update task 'Meeting' to have a 2 day duration"

# Task identification by ID (more reliable than name search)
"Get task with ID 1234567890"
"Update task ID 1234567890 to priority 4"
"Complete task with ID 1234567890"
"Reopen task with ID 1234567890"
"Delete task ID 1234567890"

Añadido rápido

La herramienta de añadido rápido analiza texto en lenguaje natural como la aplicación de Todoist, admitiendo múltiples funciones en un solo comando:

"Quick add: Buy groceries tomorrow #Shopping @errands p1"
"Quick add: Review PR next Monday #Work @code-review p2 //Check error handling"
"Quick add: Call mom {deadline in 3 days}"
"Quick add: Team meeting today at 2pm #Work @meetings with reminder 1 hour before"

Sintaxis de añadido rápido:

• Fechas de vencimiento: Fechas en lenguaje natural como "mañana", "el próximo viernes", "23 de enero", "en 3 días"
• Proyectos: #ProjectName (sin espacios en los nombres de proyectos)
• Etiquetas: @label (p. ej., "@urgente", "@trabajo")
• Asignados: +name (para proyectos compartidos)
• Prioridad: p1 (urgente), p2, p3, p4 (más baja)
• Fechas límite: {in 3 days} o {March 15}
• Descripciones: //your description here (debe estar al final)

Gestión de subtareas

"Create subtask 'Prepare agenda' under task 'Team Meeting'"
"Create multiple subtasks for 'Launch Project': 'Design UI', 'Write tests', 'Deploy'"
"Convert task 'Code Review' to a subtask of 'Release v2.0'"
"Promote subtask 'Bug Fix' to a main task"
"Show me the task hierarchy for 'Launch Project' with completion tracking"

Operaciones masivas

"Create multiple tasks for project launch: 'Design mockups', 'Write documentation', 'Set up CI/CD'"
"Update all high priority tasks to be due next week"
"Complete all tasks containing 'review' in project 12345"
"Delete all tasks with priority 1 that are overdue"

Gestión de comentarios

"Add comment 'This needs urgent attention' to task 'Review PR'"
"Add comment with attachment to task 67890"
"Show all comments for task 'Team Meeting'"
"Get comments for project 12345"

Gestión de etiquetas

"Show me all my labels"
"Create a new label called 'Urgent' with red color"
"Update the 'Work' label to be blue and mark as favorite"
"Delete the unused 'Old Project' label"
"Get usage statistics for all my labels"

Gestión de recordatorios (Pro/Business)

"Show me all my reminders"
"Get reminders for task 'Team Meeting'"
"Create a reminder for task 'Review PR' 30 minutes before due"
"Create an absolute reminder for task 12345 at 2024-12-25T09:00:00Z"
"Update reminder 67890 to trigger at 10:00 instead"
"Delete reminder 67890"

Descubrimiento de tareas

"Show all my tasks"
"List high priority tasks due this week"
"Get tasks in project 12345"

Pruebas y validación

"Test my Todoist connection"
"Run basic tests on all Todoist features" // Default: read-only API tests
"Run enhanced tests on all Todoist features" // Full CRUD testing with cleanup
"Benchmark Todoist API performance with 10 iterations"
"Validate that all MCP tools are working correctly"

Pruebas en modo de prueba

Cuando el modo de prueba está activado (DRYRUN=true), usa comandos normales: se simularán automáticamente:

"Create a test task with priority 1"
"Update all overdue tasks to be due tomorrow"
"Delete all completed tasks in project 12345"
"Create 5 subtasks under task 'Project Planning'"

Todas estas operaciones se validarán con tus datos reales pero no realizarán ningún cambio.

Desarrollo

Compilar desde el código fuente

# Clone the repository
git clone https://github.com/greirson/mcp-todoist.git

# Navigate to directory
cd mcp-todoist

# Install dependencies
npm install

# Build the project
npm run build

Comandos de desarrollo

# Watch for changes and rebuild
npm run watch

# Run tests
npm run test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Check formatting
npm run format:check

Arquitectura

El código sigue una arquitectura limpia y modular diseñada para mantenibilidad y escalabilidad:

Estructura principal

• src/index.ts: Punto de entrada principal del servidor con enrutamiento de solicitudes
• src/types.ts: Definiciones de tipos e interfaces de TypeScript
• src/type-guards.ts: Funciones de validación de tipos en tiempo de ejecución
• src/validation.ts: Validación y saneamiento de entradas
• src/errors.ts: Tipos de error personalizados con manejo estructurado
• src/cache.ts: Caché en memoria para optimización del rendimiento

Organización modular de herramientas

• src/tools/: Definiciones de herramientas MCP específicas de dominio organizadas por funcionalidad:
  • task-tools.ts - Gestión de tareas (9 herramientas)
  • subtask-tools.ts - Operaciones de subtareas (5 herramientas)
  • project-tools.ts - Gestión de proyectos/secciones (4 herramientas)
  • comment-tools.ts - Operaciones de comentarios (2 herramientas)
  • label-tools.ts - Gestión de etiquetas (5 herramientas)
  • reminder-tools.ts - Operaciones de recordatorios (4 herramientas)
  • test-tools.ts - Pruebas y validación (3 herramientas)
  • index.ts - Exportaciones centralizadas

Manejadores de lógica de negocio

• src/handlers/: Módulos de lógica de negocio separados por dominio:
  • task-handlers.ts - CRUD de tareas y operaciones masivas
  • subtask-handlers.ts - Gestión jerárquica de tareas
  • project-handlers.ts - Operaciones de proyectos y secciones
  • comment-handlers.ts - Creación y recuperación de comentarios
  • label-handlers.ts - CRUD y estadísticas de etiquetas
  • reminder-handlers.ts - CRUD de recordatorios mediante la API de sincronización
  • test-handlers.ts - Infraestructura de pruebas de API
  • test-handlers-enhanced/ - Marco integral de pruebas CRUD

Módulos de utilidades

• src/utils/: Funciones de utilidad compartidas:
  • api-helpers.ts - Utilidades de manejo de respuestas de API
  • error-handling.ts - Gestión centralizada de errores
  • parameter-transformer.ts - Conversión de formato de parámetros de MCP a SDK de Todoist
  • dry-run-wrapper.ts - Implementación del modo de prueba

Registro de cambios

Consulta CHANGELOG.md para obtener un historial detallado de todos los cambios.

Para guías de migración y cambios importantes, consulta el registro de cambios completo.

Contribuciones

¡Las contribuciones son bienvenidas! Este proyecto se mantiene activamente y agradezco el interés de la comunidad en mejorarlo.

Nota sobre contribuciones asistidas por IA

Utilizo Claude Code como parte de mi propio flujo de trabajo de desarrollo: la codificación asistida por IA es una parte normal de cómo se construye este proyecto. Animo a los contribuyentes a usar las herramientas que les hagan productivos, incluidos los asistentes de codificación con IA.

Dicho esto, las herramientas de IA facilitan mucho la generación de grandes volúmenes de código que parece correcto pero introduce problemas sutiles: asignaciones incorrectas de API, regresiones de rendimiento, cambios de tipos que rompen la compatibilidad o expansión del alcance que agrupa funciones no relacionadas. He visto solicitudes de extracción que cambian un prefijo de URL sin darse cuenta de que las rutas de la API en sí cambiaron, o que añaden paginación obteniendo todas las páginas cada vez sin preservar el parámetro limit.

Debido a esto, cada solicitud de extracción recibe una revisión arquitectónica exhaustiva. No se trata de restringir el acceso: se trata de mantener un código del que dependen cientos de personas a través de sus clientes MCP. Las solicitudes de extracción que parecen ser producción de IA sin revisar recibirán comentarios detallados sobre qué debe cambiar y por qué, para que puedas aprender y volver a enviarlas.

Requisitos para solicitudes de extracción

Antes de enviar una solicitud de extracción, asegúrate de:

1. Un solo tema por solicitud de extracción. Una corrección de errores es una solicitud de extracción. Una nueva función es otra. Una actualización de documentación es otra. Si tu diff toca más de 40 archivos en funciones no relacionadas, debe dividirse. Las solicitudes de extracción de alcance mixto se devolverán para dividirlas.

2. Entiendes lo que hace tu código. Si una herramienta de IA lo escribió, léelo críticamente antes de enviarlo. ¿Puedes explicar por qué cada cambio es necesario? ¿Podrías depurarlo si se rompiera? Si no, no está listo.

3. Se incluyen o actualizan pruebas. Las nuevas funcionalidades necesitan pruebas. Las correcciones de errores necesitan una prueba que habría detectado el error. Si estás cambiando endpoints de API, verifica que funcionen contra la API en vivo — no confíes solo en que un cambio de URL sea suficiente.

4. Se realiza verificación manual. Ejecuta npm run build y npm test localmente. Si estás cambiando código de integración de API, prueba contra tu propia cuenta de Todoist (el modo de prueba en seco está disponible con DRYRUN=true). Incluye evidencia de la verificación en la descripción de tu PR.

5. CI debe pasar. Los PRs con verificaciones de CI fallidas no serán revisados hasta que estén en verde.

Qué Hace un Buen PR

• Un título y cuerpo claros y descriptivos que expliquen qué y por qué
• Un diff enfocado que sea fácil de revisar (idealmente menos de 200 líneas cambiadas)
• Pruebas que demuestren que el cambio funciona
• Documentación actualizada si el cambio afecta el comportamiento visible para el usuario
• Sin cambios de formato no relacionados, refactorizaciones o mejoras "ya que estoy aquí"

Cómo Empezar

1. Haz un fork del repositorio
2. Crea una rama de funcionalidad desde main
3. Haz tus cambios siguiendo las pautas anteriores
4. Ejecuta npm run build && npm test && npm run lint para verificar
5. Envía tu PR con una descripción clara

Si no estás seguro de si un cambio es deseado o cómo abordarlo, abre un issue primero para discutirlo. Esto ahorra tiempo a todos y ayuda a alinearse en el enfoque correcto antes de escribir código.

Licencia

Este proyecto está licenciado bajo la Licencia MIT — consulta el archivo LICENSE para más detalles.

Problemas y Soporte

Si encuentras algún problema o necesitas soporte, por favor crea un issue en el repositorio de GitHub.