Skip to main content
Glama

Todoist MCP Helper ✅

English | 中文

PyPI License: MIT Sponsor

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

get_tasks, get_task, create_task, update_task, close_task, delete_task, reopen_task

Full task CRUD with priority, due dates, labels

🚚 Move

move_task, move_task_by_name

Move tasks across projects, sections, parents

🔍 Smart Search

search_task_by_name, complete_task_by_name, delete_task_by_name, update_task_by_name

Find and operate on tasks by name (fuzzy matching)

📁 Projects

list_projects, create_project, update_project, delete_project, get_project_overview

Manage projects + full structure overview

📑 Sections

list_sections, create_section, update_section, delete_section

Organize and rename sections

🏷️ Labels

list_labels, create_label

Tag management

💬 Comments

get_comments, create_comment

Task & project comments

⚙️ Config

set_api_token, get_current_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-helper

Don't have uv? Install it: curl -LsSf https://astral.sh/uv/install.sh | sh

Option B: Install with pip

pip install todoist-mcp-helper

Get Your API Token

  1. Go to Todoist Settings → Integrations

  2. Scroll to Developer → copy your API Token


📋 Configuration

All credentials are passed via environment variables — no tokens in code.

Variable

Description

Required

TODOIST_API_TOKEN

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 runtime

  • get_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 tools
close_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

    A3.5/5.0

    Scored across 28 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers