todoist-v1-mcp-server
Provides tools for interacting with Todoist's API v1, enabling AI agents to manage tasks, projects, sections, and labels programmatically through the Todoist platform.
todoist-v1-mcp-server
A clean, reliable MCP (Model Context Protocol) server for Todoist — built on the Todoist unified API v1.
Why this exists
The official Todoist web MCP (todoist-ai) has a known persistent disconnection bug on the Anthropic side that requires reconnecting daily. Community alternatives are either built on the deprecated REST API v2 or have schema validation bugs that cause failures when Todoist returns additional fields as their API evolves.
This server:
Targets the current Todoist API v1 (not deprecated v2)
Uses stdio transport — no cloud dependency, no daily reconnections
Uses the modern MCP SDK
registerTool()API (not the deprecatedsetRequestHandlerpattern)Never enforces strict output schemas on API responses — Todoist can add new fields freely without breaking anything
Zero SDK wrapper dependency — direct HTTP calls via axios, so there's no intermediary library drifting from the API
Related MCP server: MCP Todoist
Tools (31 total)
Tasks
Tool | Description |
| List/filter tasks — supports Todoist filter strings like |
| Get a single task by ID |
| Create a task with natural language due dates ( |
| Update any field; pass |
| Mark a task as done |
| Reopen a completed task |
| Permanently delete a task |
Projects
Tool | Description |
| List all projects |
| Get a single project by ID |
| Create a project (with color, view style, parent) |
| Update a project |
| Permanently delete a project and all its tasks |
Sections
Tool | Description |
| List sections within a project |
| Create a section |
| Rename a section |
| Delete a section |
Labels
Tool | Description |
| List all personal labels |
| Create a label |
| Update a label |
| Delete a label |
Comments
Tool | Description |
| List comments on a task or project (paginated) |
| Get a single comment by ID |
| Add a comment to a task or project (Markdown supported) |
| Edit an existing comment's content |
| Permanently delete a comment |
Completed tasks (Pro)
Tool | Description |
| Query completed tasks by completion date (≤3mo) or due date (≤6wk). Pro-only. |
Reminders (Pro)
Tool | Description |
| List reminders, optionally filtered by |
| Get a single reminder by ID. Pro-only. |
| Create a relative ( |
| Update reminder timing or notification service. Pro-only. |
| Permanently delete a reminder. Pro-only. |
Pro-tier handling: Reminders and completed-task queries require a Todoist Pro subscription. If the API returns a Pro-gate error (HTTP 402, or 403 with a
premium/pro/upgrade/paid/subscriptionkeyword), the server returns a clean message explaining the feature requires Pro rather than leaking the raw API error.
Setup
1. Get your Todoist API token
Go to Todoist → Settings → Integrations → Developer and copy your API token.
2. Install and build
git clone https://github.com/christulino/todoist-v1-mcp-server
cd todoist-v1-mcp-server
npm install
npm run build3. Configure Claude Desktop
Edit ~/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"
}
}
}
}Restart Claude Desktop. You should see "todoist" in the connected MCP servers.
4. Configure Claude Code (optional)
claude mcp add todoist -- node /absolute/path/to/todoist-v1-mcp-server/dist/index.jsThen set the env var:
export TODOIST_API_TOKEN=your_api_token_hereOr add it to your shell profile.
Usage examples
Once connected, Claude can handle natural language like:
"What's on my plate today?" → uses
todoist_get_taskswithfilter: "today""Add a task to call the dentist next Tuesday" → uses
todoist_create_task"Mark the dentist task as done" → uses
todoist_complete_task"Show me everything overdue" → uses
todoist_get_taskswithfilter: "overdue""Create a project called Home Renovation" → uses
todoist_create_project"What projects do I have?" → uses
todoist_get_projects
Todoist filter syntax
The filter parameter in todoist_get_tasks supports Todoist's full natural language filter syntax:
Filter | Meaning |
| Due today |
| Past due |
| Due in the next 7 days |
| Priority urgent |
| Tasks in a specific project |
| Tasks with a specific label |
| Tasks without a due date |
| Today or overdue (combine with |
| Today AND labeled 'waiting' |
Full filter documentation: https://todoist.com/help/articles/introduction-to-filters
Requirements
Node.js 18+
A Todoist account (free tier works)
Development
npm run dev # tsx watch mode with auto-reload
npm run build # compile TypeScript
npm start # run compiled serverTesting
The test suite hits the live Todoist API and runs a full CRUD cycle across tasks, projects, sections, labels, comments, and reminders, plus a read-only smoke test for completed-task querying. Reminders and completed-task tests detect Pro-tier gating (HTTP 402/403) and report cleanly when the account is on the Free tier. All test data is prefixed with [mcp-test] and cleaned up automatically.
TODOIST_API_TOKEN=your_token npm testYour API token is at Todoist → Settings → Integrations → Developer — same token you put in claude_desktop_config.json.
Contributing
PRs welcome. The goal is a minimal, correct implementation that stays current with the Todoist API v1. Priorities:
Correctness over cleverness
Permissive output handling (never reject unknown API fields)
Helpful error messages that tell you what went wrong and how to fix it
License
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.99 npm2MIT
- AlicenseBqualityDmaintenanceA Model Context Protocol server implementation compatible with Todoist API, allowing AI agents to interact with task management functionality through standardized MCP tools.518 npm1MIT
- AlicenseAqualityDmaintenanceMCP Server to create and manage tasks, projects, labels and more in Todoist, using their unified v1 API729 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