Todoist MCP Server
Provides comprehensive task management through Todoist, enabling the creation, organization, and tracking of tasks, projects, sections, and labels, along with productivity statistics and natural language task entry.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Todoist MCP Server Add a task to review the design doc tomorrow morning"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Todoist MCP Server
An MCP (Model Context Protocol) server that provides comprehensive task management through Todoist. This enables AI assistants like Claude to create, manage, and organize tasks using natural language.
Features
Tools (21 total)
Tool | Description |
| List tasks with filtering (by project, priority, due date, etc.) |
| Get detailed task info including comments and subtasks |
| Create tasks with natural language due dates |
| Update task content, due date, priority, labels |
| Mark tasks complete (handles recurring) |
| Reopen completed tasks |
| Permanently delete tasks |
| Move tasks between projects/sections |
| List all projects |
| Create new projects |
| Update project name, color, view style |
| Permanently delete projects |
| List sections within projects |
| Create sections |
| Rename or collapse/expand sections |
| Move sections between projects |
| Permanently delete sections |
| List all labels |
| Create new labels |
| Update label name, color, order |
| Permanently delete labels |
| Add comments to tasks |
| Get completion statistics |
| Natural language task entry |
Resources
Resource | Description |
| Today's tasks including overdue |
| Tasks due in the next 7 days |
| All overdue tasks |
| Project overview with task counts |
| Labels and usage counts |
Prompts
Prompt | Description |
| Morning planning workflow |
| GTD-style weekly review |
| Rapid multi-task capture |
| Break large tasks into subtasks |
Related MCP server: Todoist MCP Server
Setup
1. Get Your Todoist API Token
Go to https://todoist.com/app/settings/integrations/developer
Scroll to "API token"
Copy your token
2. Install Dependencies
cd todoist-mcp
npm install3. Build
npm run build4. Add to Claude Code
claude mcp add --transport stdio todoist \
--env TODOIST_API_TOKEN=your_token_here \
-- node /path/to/todoist-mcp/dist/index.jsOr add manually to your Claude Code configuration:
{
"mcpServers": {
"todoist": {
"command": "node",
"args": ["/path/to/todoist-mcp/dist/index.js"],
"env": {
"TODOIST_API_TOKEN": "your_token_here"
}
}
}
}5. Verify Connection
In Claude Code, type /mcp to check the server is connected.
Usage Examples
Create a Task
"Add a task to review the budget report by Friday"The AI will use create_task with natural language due date parsing.
View Today's Tasks
"What do I need to do today?"Uses the todoist://today resource or list_tasks with dueToday: true.
Daily Planning
"Let's do my daily planning"Invokes the daily_planning prompt for a guided planning session.
Quick Capture
"Add these tasks: call dentist tomorrow, review PR by EOD, update docs"Uses quick_add or create_task for natural language entry.
Initialize GTD Structure (One-Time Setup)
Run the setup script to create a GTD-inspired structure:
TODOIST_API_TOKEN=your_token npx tsx scripts/setup-gtd-structure.tsThis creates:
Projects: Work, Personal (with sub-projects), Recurring, Someday/Maybe, Reference
Labels: Context (@computer, @phone), Energy (@high-energy), Time (@5min, @deep-work), Status (@waiting-for)
Natural Language Due Dates
Todoist supports flexible date parsing:
Input | Result |
| Today |
| Tomorrow |
| Tomorrow at 2:00 PM |
| Next Monday |
| 3 days from now |
| January 15 |
| Daily recurring |
| Weekly on Monday at 9 AM |
| Monday through Friday |
Priority Mapping
API Value | Display | Color |
| P1 (highest) | Red |
| P2 | Orange |
| P3 | Yellow |
| P4 (default) | None |
Rate Limiting
The server implements rate limiting to stay within Todoist's API limits:
Limit: 450 requests per 15 minutes
Caching: Projects and labels are cached for 5 minutes
Development
Run in Development Mode
npm run devThis runs TypeScript in watch mode.
Test with MCP Inspector
npm run inspectOpens the MCP Inspector for testing tools and resources.
Project Structure
todoist-mcp/
├── src/
│ ├── index.ts # Entry point
│ ├── types/ # TypeScript type definitions
│ ├── services/ # Todoist client, caching, rate limiting
│ ├── tools/ # MCP tool implementations
│ ├── resources/ # MCP resource implementations
│ └── prompts/ # MCP prompt implementations
├── dist/ # Compiled output
├── package.json
└── tsconfig.jsonTroubleshooting
"TODOIST_API_TOKEN environment variable is required"
Make sure you've set the token in your MCP configuration:
claude mcp add --env TODOIST_API_TOKEN=your_token ...Rate Limit Errors
The server automatically handles rate limiting, but if you hit limits:
Wait 15 minutes for the window to reset
Check
get_productivity_statsto see current rate limit usage
Tasks Not Appearing
Verify your API token is correct
Check that tasks aren't filtered out (completed, different project, etc.)
Use
list_taskswithout filters to see all tasks
Quick Add Project Assignment
The quick_add tool uses Todoist's natural language parser, which may not always parse project names with spaces correctly. For example, "Task #My Project" might not assign to the "My Project" project.
Workaround: Use create_task with explicit projectId for reliable project assignment, or use project names without spaces.
License
MIT
Available Tools
24 toolsadd_commentC
Add a comment to a task
Inputs: taskId (required), content (required).
complete_taskA
Mark a task as complete. For recurring tasks, this completes the current occurrence.
Inputs: taskId (required).
create_labelC
Create a new label
Inputs: name (required), color, isFavorite.
create_projectC
Create a new project
Inputs: name (required), color, parentId, isFavorite, +1 more.
create_sectionC
Create a new section within a project
Inputs: projectId (required), name (required).
create_taskC
Create a new task with optional due date, priority, labels, and project
Inputs: content (required), description, projectId, sectionId, +8 more.
delete_labelA
Permanently delete a label (tasks will keep their other labels)
Inputs: labelId (required).
delete_projectB
Permanently delete a project and all its tasks
Inputs: projectId (required).
delete_sectionB
Permanently delete a section (tasks will be moved to project root)
Inputs: sectionId (required).
delete_taskC
Permanently delete a task
Inputs: taskId (required).
get_productivity_statsC
Get task completion statistics and productivity insights
Inputs: period.
get_taskB
Get detailed information about a specific task including comments and subtasks
Inputs: taskId (required), includeComments.
list_labelsB
List all labels in the Todoist account
Inputs: no named parameters.
list_projectsB
List all projects in the Todoist account
Inputs: no named parameters.
list_sectionsC
List sections within a project
Inputs: projectId.
list_tasksB
List tasks with optional filtering by project, label, priority, due date, or custom filter
Inputs: projectId, sectionId, priority, dueToday, +5 more.
move_sectionC
Move a section to a different project
Inputs: sectionId (required), projectId (required).
move_taskC
Move a task to a different project, section, or make it a subtask
Inputs: taskId (required), projectId, sectionId, parentId.
quick_addA
Quickly add a task using natural language. Todoist will parse dates, priorities, labels, and projects from the text.
Inputs: text (required).
uncomplete_taskC
Reopen a completed task
Inputs: taskId (required).
update_labelC
Update an existing label (name, color, favorite status, order)
Inputs: labelId (required), name, color, order, +1 more.
update_projectC
Update an existing project (name, color, favorite status, view style)
Inputs: projectId (required), name, color, isFavorite, +1 more.
update_sectionC
Update a section (rename or collapse/expand)
Inputs: sectionId (required), name, collapsed.
update_taskC
Update an existing task (content, due date, priority, labels, etc.)
Inputs: taskId (required), content, description, labels, +6 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
Every tool has a clearly distinct purpose targeting specific resources (tasks, projects, labels, sections) and actions (create, get, list, update, delete, move, complete). No ambiguity exists; for example, create_task vs. quick_add are differentiated by input method, and move_task vs. update_task handle different aspects of task modification.
All tools follow a consistent verb_noun pattern (e.g., create_task, list_labels, update_project) with no deviations. The naming is uniform and predictable, making it easy for agents to understand and select tools based on their actions and targets.
With 24 tools, the count is borderline high for a todo management server, potentially feeling heavy. While each tool serves a specific function, the number might overwhelm agents, as typical well-scoped servers have 3-15 tools. However, it's not extreme enough to score lower.
The tool set provides complete CRUD/lifecycle coverage for the Todoist domain, including tasks, projects, labels, and sections. It covers all essential operations from creation to deletion, with additional utilities like moving, commenting, and productivity stats, leaving no obvious gaps for agent workflows.
Related MCP Connectors
AI-powered to-do list: add, list, complete and organise tasks across lists from any assistant.
Manage tasks, Focus Zone, notes, projects, and task history from compatible AI assistants.
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
Your AI planner: add, find, move and complete tasks, plan your days and track goals.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Todoist tasks, projects, labels, sections, and comments through natural conversation. Supports comprehensive task operations including creation, updates, completion, and organization with natural language quick-add functionality.-
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with Todoist tasks and projects through natural language. Supports comprehensive task management including creating, updating, completing tasks, managing projects, and filtering by various criteria.11GPL 3.0
- AlicenseNot gradedqualityDmaintenanceConnects AI assistants to Todoist for comprehensive task management, enabling natural language creation, updating, and organization of tasks, projects, sections, and labels.17 npm3MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Todoist tasks, projects, sections, and labels through natural language, supporting task creation, updates, completion, and intelligent organization of your workflow.MIT