todoist-mcp-helper 1.2.0

MCP Server for Todoist — Connect AI agents to your Todoist tasks

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	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.

---

🚀 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:

uvx (recommended)	pip
{ "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:

uvx (recommended)	pip
{ "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:

uvx (recommended)	pip
{ "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.