Todoist MCP Helper
Manage Todoist tasks (create, search, complete, move, update, delete, reopen) and projects, sections, labels, and comments via the Todoist API.
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 Helper show me my incomplete tasks for this week"
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 Helper ✅
English | 中文
Connect AI agents to your Todoist tasks via the Model Context Protocol (MCP).
Create, search, complete, and manage your Todoist tasks — all from Claude, Gemini, Cursor, or any MCP-compatible AI agent.
✨ Features
Category | Tools | Description |
📋 Tasks |
| Full task CRUD with priority, due dates, labels |
🚚 Move |
| Move tasks across projects, sections, parents |
🔍 Smart Search |
| Find and operate on tasks by name (fuzzy matching) |
📁 Projects |
| Manage projects + full structure overview |
📑 Sections |
| Organize and rename sections |
🏷️ Labels |
| Tag management |
💬 Comments |
| Task & project comments |
⚙️ Config |
| Runtime token management |
27 tools total — the most comprehensive Todoist MCP server available.
Related MCP server: MCP Todoist
🚀 Quick Start
Option A: Quick Run with uvx (Recommended)
No installation needed — runs in a temporary isolated environment:
uvx todoist-mcp-helperDon't have
uv? Install it:curl -LsSf https://astral.sh/uv/install.sh | sh
Option B: Install with pip
pip install todoist-mcp-helperGet Your API Token
Scroll to Developer → copy your API Token
📋 Configuration
All credentials are passed via environment variables — no tokens in code.
Variable | Description | Required |
| Your Todoist API Token | ✅ |
🔧 Platform Configuration
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"todoist": {
"command": "uvx",
"args": ["todoist-mcp-helper"],
"env": {
"TODOIST_API_TOKEN": "your_token"
}
}
}
}{
"mcpServers": {
"todoist": {
"command": "todoist-mcp-helper",
"env": {
"TODOIST_API_TOKEN": "your_token"
}
}
}
}Gemini CLI
Add to ~/.gemini/settings.json:
{
"mcpServers": {
"todoist": {
"command": "uvx",
"args": ["todoist-mcp-helper"],
"env": {
"TODOIST_API_TOKEN": "your_token"
}
}
}
}{
"mcpServers": {
"todoist": {
"command": "todoist-mcp-helper",
"env": {
"TODOIST_API_TOKEN": "your_token"
}
}
}
}Cursor
Add to .cursor/mcp.json:
{
"mcpServers": {
"todoist": {
"command": "uvx",
"args": ["todoist-mcp-helper"],
"env": {
"TODOIST_API_TOKEN": "your_token"
}
}
}
}{
"mcpServers": {
"todoist": {
"command": "todoist-mcp-helper",
"env": {
"TODOIST_API_TOKEN": "your_token"
}
}
}
}CherryStudio / Other MCP Clients
{
"todoist": {
"command": "uvx",
"args": ["todoist-mcp-helper"],
"env": {
"TODOIST_API_TOKEN": "your_token"
}
}
}ModelScope (魔塔)
Select Stdio mode in the MCP service configuration, then use:
{
"mcpServers": {
"todoist": {
"command": "uvx",
"args": ["todoist-mcp-helper"],
"env": {
"TODOIST_API_TOKEN": "your_token"
}
}
}
}Add TODOIST_API_TOKEN in the environment variables section with your API token value.
💡 Usage Examples
Once configured, ask your AI agent:
"Show me my tasks for today"
"Create a task: Buy groceries, due tomorrow, priority 2"
"Complete the task about groceries"
"Move the grocery task to my Shopping project"
"Search for tasks related to meeting"
"List all my projects"
"Show me the full project overview with sections"
"Add a comment to my latest task"
🔐 Runtime Configuration
Change tokens without restarting:
set_api_token— Switch Todoist account at runtimeget_current_config— Check current configuration
💖 Support
If this project helps you, consider buying me a coffee! Your support keeps this project alive and growing ✨
☕ 爱发电 (Afdian)
Supports Alipay & WeChat Pay
💎 Crypto (USDC / ERC-20)
Click to donate — supports MetaMask, SafePal & more
Every little bit helps — thank you! 🙏
📄 License
MIT License — see LICENSE for details.
Available Tools
28 toolsclose_taskC
Close (complete) a task.
Args: task_id: ID of the task to close.
Inputs: task_id (required). Returns: result
complete_task_by_nameA
Complete a task by searching for it by name. Uses partial name matching. If multiple tasks match, lists them for the user to choose.
Args: task_name: Name/content of the task to find and complete.
Inputs: task_name (required). Returns: result
create_commentA
Add a comment to a task or project. Must provide either task_id or project_id.
Args: content: The comment text. task_id: ID of the task to comment on. project_id: ID of the project to comment on.
Inputs: content (required), task_id, project_id. Returns: result
create_labelB
Create a new personal label.
Args: name: Name of the label. color: Optional color (e.g. 'berry_red', 'blue', 'charcoal').
Inputs: name (required), color. Returns: result
create_projectB
Create a new project.
Args: name: Name of the project. color: Optional color (e.g. 'berry_red', 'blue', 'charcoal'). parent_id: Optional parent project ID to create as a sub-project.
Inputs: name (required), color, parent_id. Returns: result
create_sectionC
Create a new section within a project.
Args: name: Name of the section. project_id: ID of the project to create the section in.
Inputs: name (required), project_id (required). Returns: result
create_taskA
Create a new task in Todoist.
Args: content: The task title/content (required). description: Optional description text. project_id: Optional project ID to add the task to. section_id: Optional section ID within a project. parent_id: Optional parent task ID (for sub-tasks). due_string: Optional due date in natural language (e.g. 'tomorrow', 'every monday', 'Jan 23'). due_date: Optional due date in YYYY-MM-DD format. priority: Priority from 1 (normal) to 4 (urgent). Default is 1. labels: Optional comma-separated label names (e.g. 'work,urgent').
Inputs: content (required), description, project_id, section_id, +5 more. Returns: result
delete_projectA
Delete a project and all its tasks.
Args: project_id: ID of the project to delete.
Inputs: project_id (required). Returns: result
delete_sectionA
Delete a section and move its tasks to the parent project.
Args: section_id: ID of the section to delete.
Inputs: section_id (required). Returns: result
delete_taskB
Permanently delete a task.
Args: task_id: ID of the task to delete.
Inputs: task_id (required). Returns: result
delete_task_by_nameA
Delete a task by searching for it by name. Uses partial name matching. If multiple tasks match, lists them for the user to choose.
Args: task_name: Name/content of the task to find and delete.
Inputs: task_name (required). Returns: result
get_commentsB
Get comments for a task or project. Must provide either task_id or project_id.
Args: task_id: ID of the task to get comments for. project_id: ID of the project to get comments for.
Inputs: task_id, project_id. Returns: result
get_current_configA
Show the current configuration status (whether API token is set, API base URL, etc).
Inputs: no named parameters. Returns: result
get_project_overviewA
Get a comprehensive overview of all projects with their sections and task counts. Useful for understanding the full project structure before organizing tasks.
Inputs: no named parameters. Returns: result
get_taskC
Get detailed information about a single task.
Args: task_id: ID of the task.
Inputs: task_id (required). Returns: result
get_tasksA
Get all active tasks. Can filter by project, label, or Todoist filter string.
Args: project_id: Optional project ID to filter tasks by. label: Optional label name to filter tasks by. filter_str: Optional Todoist filter string (e.g. 'today', 'overdue', 'p1').
Inputs: project_id, label, filter_str. Returns: result
list_labelsA
List all personal labels in the user's Todoist account.
Inputs: no named parameters. Returns: result
list_projectsA
List all projects in the user's Todoist account. Returns project names, IDs, and colors.
Inputs: no named parameters. Returns: result
list_sectionsB
List sections, optionally filtered by project.
Args: project_id: Optional project ID to filter sections by.
Inputs: project_id. Returns: result
move_taskB
Move a task to a different project, section, or under a parent task. This enables cross-project task organization.
Args: task_id: ID of the task to move (required). project_id: ID of the target project to move the task to. section_id: ID of the target section to move the task to. parent_id: ID of the parent task to move the task under.
Inputs: task_id (required), project_id, section_id, parent_id. Returns: result
move_task_by_nameA
Move a task to a different project/section by searching for it by name. Uses partial name matching. If multiple tasks match, lists them for the user to choose.
Args: task_name: Name/content of the task to find and move. project_id: ID of the target project to move the task to. section_id: ID of the target section to move the task to. parent_id: ID of the parent task to move the task under.
Inputs: task_name (required), project_id, section_id, parent_id. Returns: result
reopen_taskB
Reopen a previously completed task.
Args: task_id: ID of the task to reopen.
Inputs: task_id (required). Returns: result
search_task_by_nameA
Search for tasks by name using partial/fuzzy matching. Returns all tasks whose title contains the search query.
Args: query: Search keyword to match against task titles (case-insensitive).
Inputs: query (required). Returns: result
set_api_tokenA
Set or update the Todoist API Token at runtime. This allows switching accounts without restarting the server. The token will persist for the current session only.
Args: token: Your Todoist API Token (get from https://app.todoist.com/app/settings/integrations).
Inputs: token (required). Returns: result
update_projectB
Update an existing project.
Args: project_id: ID of the project to update. name: New name for the project. color: New color for the project. is_favorite: Whether to mark as favorite.
Inputs: project_id (required), name, color, is_favorite. Returns: result
update_sectionB
Rename an existing section.
Args: section_id: ID of the section to update. name: New name for the section.
Inputs: section_id (required), name (required). Returns: result
update_taskB
Update an existing task.
Args: task_id: ID of the task to update (required). content: New task title/content. description: New description. due_string: New due date in natural language. due_date: New due date in YYYY-MM-DD format. due_datetime: New due date and time in RFC3339 format. priority: New priority (1-4). labels: New comma-separated label names (replaces existing labels). assignee_id: ID of user to assign the task to. duration: Task duration in minutes or days (requires duration_unit). duration_unit: Unit for duration: 'minute' or 'day'. deadline_date: Deadline date in YYYY-MM-DD format.
Inputs: task_id (required), content, description, due_string, +8 more. Returns: result
update_task_by_nameA
Update a task by searching for it by name. Uses partial name matching. If multiple tasks match, lists them for the user to choose.
Args: task_name: Name/content of the task to find and update. content: New task title. description: New description. due_string: New due date in natural language (e.g. 'tomorrow', 'next Monday'). priority: New priority (1-4).
Inputs: task_name (required), content, description, due_string, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Tools are clearly separated by action (create, read, update, delete, close, reopen, move) and input method (ID vs. name-based variants like `complete_task_by_name` vs `close_task`). Some overlap exists between name-based and ID-based tools for the same action, which may cause confusion if the agent doesn't check arguments, but descriptions clarify the distinction.
All tools use a consistent `verb_noun` pattern in snake_case (e.g., `create_task`, `list_projects`, `get_comments`). The `by_name` suffix is uniformly applied to name-based variants. Naming is predictable and easy to navigate.
With 28 tools, the count is above average but appropriate for a full-featured Todoist integration. The inclusion of both ID- and name-based variants for key operations slightly inflates the count, but each tool serves a distinct use case for agents that may or may not have IDs.
The tool surface covers all major Todoist entities (projects, sections, tasks, labels, comments, configuration) and supports core CRUD plus close/reopen/move operations. Minor gaps exist: no delete or update for labels, no update or delete for comments, and no project sharing functionality.
Maintenance
Related MCP Connectors
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
Task management your AI agents can actually run. One line becomes a context-ready task over MCP.
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
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
- AlicenseBqualityDmaintenanceProvides Todoist task management capabilities to AI assistants through the Model Context Protocol. Enables users to interact with their Todoist projects and tasks directly through Claude Desktop using natural language commands.33MIT
- 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