todoist-v1-mcp-server
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ónsetRequestHandlerobsoleto)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 |
| Lista/filtra tareas: admite cadenas de filtro de Todoist como |
| Obtiene una sola tarea por ID |
| Crea una tarea con fechas de vencimiento en lenguaje natural ( |
| Actualiza cualquier campo; pasa |
| Marca una tarea como completada |
| Reabre una tarea completada |
| Elimina permanentemente una tarea |
Proyectos
Herramienta | Descripción |
| Lista todos los proyectos |
| Obtiene un solo proyecto por ID |
| Crea un proyecto (con color, estilo de vista, padre) |
| Actualiza un proyecto |
| Elimina permanentemente un proyecto y todas sus tareas |
Secciones
Herramienta | Descripción |
| Lista las secciones dentro de un proyecto |
| Crea una sección |
| Cambia el nombre de una sección |
| Elimina una sección |
Etiquetas
Herramienta | Descripción |
| Lista todas las etiquetas personales |
| Crea una etiqueta |
| Actualiza una etiqueta |
| Elimina una etiqueta |
Comentarios
Herramienta | Descripción |
| Lista los comentarios en una tarea o proyecto (paginado) |
| Obtiene un solo comentario por ID |
| Añade un comentario a una tarea o proyecto (se admite Markdown) |
| Edita el contenido de un comentario existente |
| Elimina permanentemente un comentario |
Tareas completadas (Pro)
Herramienta | Descripción |
| Consulta tareas completadas por fecha de finalización (≤3 meses) o fecha de vencimiento (≤6 semanas). Solo Pro. |
Recordatorios (Pro)
Herramienta | Descripción |
| Lista recordatorios, opcionalmente filtrados por |
| Obtiene un solo recordatorio por ID. Solo Pro. |
| Crea un recordatorio relativo ( |
| Actualiza el tiempo del recordatorio o el servicio de notificación. Solo Pro. |
| 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 build3. 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.jsLuego establece la variable de entorno:
export TODOIST_API_TOKEN=your_api_token_hereO 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_tasksconfilter: "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_tasksconfilter: "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 |
| Vence hoy |
| Vencido |
| Vence en los próximos 7 días |
| Prioridad urgente |
| Tareas en un proyecto específico |
| Tareas con una etiqueta específica |
| Tareas sin fecha de vencimiento |
| Hoy o vencido (combina con |
| 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 serverPruebas
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 testTu 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:
Corrección sobre ingenio
Manejo permisivo de la salida (nunca rechazar campos de API desconocidos)
Mensajes de error útiles que te digan qué salió mal y cómo solucionarlo
Licencia
MIT
Available Tools
20 toolstodoist_complete_taskComplete Todoist TaskAIdempotent
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 LabelADestructive
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 ProjectADestructive
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 SectionADestructive
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 TaskADestructive
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 LabelsARead-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 ProjectARead-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 ProjectsARead-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 SectionsARead-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 TaskARead-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 TasksARead-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 TaskAIdempotent
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 LabelAIdempotent
Update an existing Todoist label. Only include fields to change.
Inputs: label_id (required), name, color, order, +1 more.
todoist_update_projectUpdate Todoist ProjectAIdempotent
Update an existing Todoist project. Only include fields to change.
Inputs: project_id (required), name, color, is_favorite, +1 more.
todoist_update_sectionUpdate Todoist SectionBIdempotent
Rename an existing Todoist section.
Inputs: section_id (required), name (required).
todoist_update_taskUpdate Todoist TaskAIdempotent
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
Scored across 20 tools
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.
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.
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.
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
Related MCP Connectors
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
Headless task management for bots, apps and AI agents. Remote MCP server, OAuth or access token.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA Model Context Protocol server that enables advanced task and project management in Todoist via Claude Desktop and other MCP-compatible clients.111 npm2MIT
- AlicenseBqualityDmaintenanceA Model Context Protocol server implementation compatible with Todoist API, allowing AI agents to interact with task management functionality through standardized MCP tools.51MIT
- AlicenseAqualityDmaintenanceMCP Server to create and manage tasks, projects, labels and more in Todoist, using their unified v1 API727 npm7GPL 3.0
- AlicenseAqualityDmaintenanceA Python MCP server that enables AI assistants to manage Todoist tasks and projects through the Model Context Protocol. It supports full CRUD operations for tasks and projects, including support for nested projects and Todoist's advanced filter syntax.11MIT