Skip to main content
Glama

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

  • Sin dependencia de envoltorios del SDK: llamadas HTTP directas a través de axios, por lo que no hay ninguna biblioteca intermedia que se desvíe de la API

Related MCP server: MCP Todoist

Herramientas (31 en total)

Tareas

Herramienta

Descripción

todoist_get_tasks

Lista/filtra tareas: admite cadenas de filtro de Todoist como "today", "overdue", "p1", "#ProjectName", "7 days"

todoist_get_task

Obtiene una sola tarea por ID

todoist_create_task

Crea una tarea con fechas de vencimiento en lenguaje natural ("tomorrow", "every monday", etc.)

todoist_update_task

Actualiza cualquier campo; pasa clear_due_date: true para eliminar una fecha de vencimiento

todoist_complete_task

Marca una tarea como completada

todoist_reopen_task

Reabre una tarea completada

todoist_delete_task

Elimina permanentemente una tarea

Proyectos

Herramienta

Descripción

todoist_get_projects

Lista todos los proyectos

todoist_get_project

Obtiene un solo proyecto por ID

todoist_create_project

Crea un proyecto (con color, estilo de vista, padre)

todoist_update_project

Actualiza un proyecto

todoist_delete_project

Elimina permanentemente un proyecto y todas sus tareas

Secciones

Herramienta

Descripción

todoist_get_sections

Lista las secciones dentro de un proyecto

todoist_create_section

Crea una sección

todoist_update_section

Cambia el nombre de una sección

todoist_delete_section

Elimina una sección

Etiquetas

Herramienta

Descripción

todoist_get_labels

Lista todas las etiquetas personales

todoist_create_label

Crea una etiqueta

todoist_update_label

Actualiza una etiqueta

todoist_delete_label

Elimina una etiqueta

Comentarios

Herramienta

Descripción

todoist_get_comments

Lista los comentarios en una tarea o proyecto (paginado)

todoist_get_comment

Obtiene un solo comentario por ID

todoist_create_comment

Añade un comentario a una tarea o proyecto (se admite Markdown)

todoist_update_comment

Edita el contenido de un comentario existente

todoist_delete_comment

Elimina permanentemente un comentario

Tareas completadas (Pro)

Herramienta

Descripción

todoist_get_completed_tasks

Consulta tareas completadas por fecha de finalización (≤3 meses) o fecha de vencimiento (≤6 semanas). Solo Pro.

Recordatorios (Pro)

Herramienta

Descripción

todoist_get_reminders

Lista recordatorios, opcionalmente filtrados por task_id. Solo Pro.

todoist_get_reminder

Obtiene un solo recordatorio por ID. Solo Pro.

todoist_create_reminder

Crea un recordatorio relativo (minute_offset antes del vencimiento) o absoluto. Solo Pro.

todoist_update_reminder

Actualiza el tiempo del recordatorio o el servicio de notificación. Solo Pro.

todoist_delete_reminder

Elimina permanentemente un recordatorio. Solo Pro.

Gestión del nivel Pro: Los recordatorios y las consultas de tareas completadas requieren una suscripción a Todoist Pro. Si la API devuelve un error de restricción Pro (HTTP 402, o 403 con una palabra clave premium/pro/upgrade/paid/subscription), el servidor devuelve un mensaje claro explicando que la función requiere Pro en lugar de filtrar el error de la API sin procesar.

Configuración

1. Obtén tu token de API de Todoist

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

2. Instala y compila

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

3. Configura 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. Configura 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?" → usa todoist_get_tasks con filter: "today"

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

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

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

  • "Crea un proyecto llamado Renovación del hogar" → usa todoist_create_project

  • "¿Qué proyectos tengo?" → usa 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:

Filtro

Significado

today

Vence hoy

overdue

Vencido

7 days

Vence en los próximos 7 días

p1

Prioridad urgente

#ProjectName

Tareas en un proyecto específico

@labelname

Tareas con una etiqueta específica

no due date

Tareas sin fecha de vencimiento

today | overdue

Hoy o vencido (combina con |)

today & @waiting

Hoy Y etiquetado como 'waiting'

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, etiquetas, comentarios y recordatorios, además de una prueba de humo de solo lectura para la consulta de tareas completadas. Las pruebas de recordatorios y tareas completadas detectan la restricción del nivel Pro (HTTP 402/403) e informan claramente cuando la cuenta está en el nivel gratuito. 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 te digan qué salió mal y cómo solucionarlo

Licencia

MIT

Available Tools

20 tools
todoist_complete_taskComplete Todoist TaskA
Idempotent

Mark a Todoist task as completed (close it).

This is the standard way to check off a task. For recurring tasks, this advances to the next occurrence rather than permanently removing it.

Use todoist_delete_task to permanently remove a task instead.

Inputs: task_id (required).

todoist_create_labelCreate Todoist LabelA

Create a new personal label in Todoist.

Returns the created label's ID and name. Use the label name (not ID) when assigning labels to tasks with todoist_create_task or todoist_update_task.

Inputs: name (required), color, order, is_favorite.

todoist_create_projectCreate Todoist ProjectA

Create a new project in Todoist.

Color options: berry_red, red, orange, yellow, olive_green, lime_green, green, mint_green, teal, sky_blue, light_blue, blue, grape, violet, lavender, magenta, salmon, charcoal, grey, taupe.

Returns the full created project object including its assigned ID.

Inputs: name (required), parent_id, color, is_favorite, +1 more.

todoist_create_sectionCreate Todoist SectionA

Create a new section within a Todoist project.

Returns the created section's ID and details. Use the section ID when creating tasks (todoist_create_task) to add them directly to this section.

Inputs: name (required), project_id (required), order.

todoist_create_taskCreate Todoist TaskA

Create a new task in Todoist.

The due_string field supports natural language: "tomorrow", "every monday", "Feb 20", "next week", "in 3 hours", etc.

Priority levels: 1=normal (default), 2=medium, 3=high, 4=urgent.

Returns the full created task object including its assigned ID.

Inputs: content (required), description, project_id, section_id, +6 more.

todoist_delete_labelDelete Todoist LabelA
Destructive

Permanently delete a personal Todoist label.

The label will be removed from all tasks that currently use it. This cannot be undone.

Inputs: label_id (required).

todoist_delete_projectDelete Todoist ProjectA
Destructive

Permanently delete a Todoist project and all its tasks. This cannot be undone.

WARNING: All tasks within the project will also be deleted.

Inputs: project_id (required).

todoist_delete_sectionDelete Todoist SectionA
Destructive

Permanently delete a Todoist section.

Tasks within the section are NOT deleted — they are moved to the parent project (unsectioned). The section itself is permanently removed and cannot be undone.

Inputs: section_id (required).

todoist_delete_taskDelete Todoist TaskA
Destructive

Permanently delete a Todoist task. This action cannot be undone.

For recurring tasks or tasks you just want to mark as done, use todoist_complete_task instead.

Inputs: task_id (required).

todoist_get_labelsGet Todoist LabelsA
Read-onlyIdempotent

List all personal labels in the user's Todoist account.

Returns label IDs, names, colors, and sort order. Use label names (not IDs) when creating or updating tasks.

Inputs: response_format.

todoist_get_projectGet Todoist ProjectA
Read-onlyIdempotent

Retrieve a single Todoist project by its ID.

Returns full project details including name, color, parent project, comment count, sharing status, and view style.

Inputs: project_id (required), response_format.

todoist_get_projectsGet Todoist ProjectsA
Read-onlyIdempotent

List all projects in the user's Todoist account.

Returns project IDs, names, colors, hierarchy (parent_id for sub-projects), and metadata like whether each project is a favorite or shared.

Use project IDs with todoist_get_tasks to fetch tasks for a specific project.

Inputs: response_format.

todoist_get_sectionsGet Todoist SectionsA
Read-onlyIdempotent

List all sections within a Todoist project.

Sections are used to organize tasks within a project into groups. Returns section IDs, names, and sort order.

Use section IDs with todoist_get_tasks (section_id param) or todoist_create_task (section_id param) to work with tasks in specific sections.

Inputs: project_id (required), response_format.

todoist_get_taskGet Todoist TaskA
Read-onlyIdempotent

Retrieve a single Todoist task by its ID.

Returns full task details: content, description, due date, priority, labels, project/section IDs, comment count, and creation timestamp.

Inputs: task_id (required), response_format.

todoist_get_tasksGet Todoist TasksA
Read-onlyIdempotent

List and filter tasks from Todoist.

Use the filter parameter for powerful natural-language Todoist filters:

  • "today" → tasks due today

  • "overdue" → past-due tasks

  • "7 days" → due in the next 7 days

  • "p1" → priority 1 (urgent)

  • "#Work" → tasks in project named Work

  • "@waiting" → tasks with label 'waiting'

  • "no due date" → tasks with no due date

  • Combine with & (AND), | (OR): "today | overdue"

Alternatively, filter by project_id, section_id, or label directly.

Returns task IDs, content, due dates, priorities, labels, and project/section IDs.

Inputs: filter, project_id, section_id, label, +3 more.

todoist_reopen_taskReopen Todoist TaskA
Idempotent

Reopen (uncomplete) a previously completed Todoist task.

Useful for tasks that were marked done by mistake or need to be revisited.

Inputs: task_id (required).

todoist_update_labelUpdate Todoist LabelA
Idempotent

Update an existing Todoist label. Only include fields to change.

Inputs: label_id (required), name, color, order, +1 more.

todoist_update_projectUpdate Todoist ProjectA
Idempotent

Update an existing Todoist project. Only include fields to change.

Inputs: project_id (required), name, color, is_favorite, +1 more.

todoist_update_sectionUpdate Todoist SectionB
Idempotent

Rename an existing Todoist section.

Inputs: section_id (required), name (required).

todoist_update_taskUpdate Todoist TaskA
Idempotent

Update an existing Todoist task.

Only include the fields you want to change — all fields are optional. To clear a due date, pass clear_due_date: true (sends due_string: "no date" — empty string is silently ignored and due: null returns 400). To remove all labels, pass labels as an empty array [].

Priority: 1=normal, 2=medium, 3=high, 4=urgent.

Inputs: task_id (required), content, description, clear_due_date, +6 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 20 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose targeting specific resources (tasks, projects, labels, sections) and actions (create, get, update, delete, complete, reopen). Descriptions explicitly differentiate similar tools (e.g., todoist_complete_task vs. todoist_delete_task), eliminating ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with the prefix 'todoist_' (e.g., todoist_create_task, todoist_get_labels). The naming is uniform across all 20 tools, using snake_case and clear action verbs aligned with CRUD operations.

    Tool Count5/5

    With 20 tools, the server provides comprehensive coverage for Todoist's domain, including tasks, projects, labels, and sections. Each tool serves a distinct, necessary function, and the count is well-scoped for managing a task management system without being excessive.

    Completeness5/5

    The tool set offers complete CRUD/lifecycle coverage for all core resources (tasks, projects, labels, sections), including specialized actions like complete, reopen, and filtering. There are no obvious gaps; agents can perform all essential operations without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers