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

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.

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