OAuthBringer/todoist-mcp

Todoist MCP Server

MCP server for Todoist API integration. Published to PyPI

Status

✅ Full Functionality - Now using Todoist unified API v1 with proper pagination support

v0.4.0 - Major expansion: Sections support, Labels management, and Batch operations

Important API Notes

Todoist has numerous API versions with incompatible ID systems:

• v1 Unified API (Todoist official ): Uses alphanumeric IDs (e.g., 69mF7QcCj9JmXxp8)
• v2 REST API: Uses numeric IDs (e.g., 7246645180)

This incompatibility means certain features like server-side search are not available in this MCP implementation, as search only exists in v2 but returns IDs incompatible with v1 operations.

Features

• Full cursor-based pagination for all endpoints
• Configurable limit parameter for all list endpoints
• Multi-auth support (environment, config file, runtime)
• Complete task and project management capabilities
• Sections support (v0.4.0): CRUD operations for project sections
• Labels management (v0.4.0): CRUD operations for labels
• Batch operations (v0.4.0): Move, update, complete multiple tasks at once
• Comment CRUD operations for tasks and projects
• Move tasks between projects, sections, and parents
• Error handling with detailed error messages

Limitations

• No server-side search (due to v1/v2 API incompatibility)
• Client-side filtering only for task queries

Installation

pip install todoist-mcp

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "todoist": {
      "command": "uvx",
      "args": ["todoist-mcp"],
      "env": {
        "TODOIST_API_TOKEN": "your_token_here"
      }
    }
  }
}

AmazonQ Developer CLI Configuration

Add to your .amazonq/mcp.json:

{
  "mcpServers": {
    "todoist": {
      "command": "uvx",
      "args": ["todoist-mcp"],
      "env": {
        "TODOIST_API_TOKEN": "your_token_here"
      }
    }
  }
}

Alternative: Using mcp-gen

For complex MCP configuration management such as in providing configurations for different contexts ot teams, use mcp-gen with YAML:

See https://github.com/OAuthBringer/mcp-gen/examples for more full examples

# mcp-config.yaml

servers:
    todoist:
      command: uvx
      args: [todoist-mcp]
      env:
        TODOIST_API_TOKEN: {{ secrets.TODOIST_API_TOKEN }}
    ```
Then generate your configuration:
```bash
`mcp-gen generate -c mcp-config.yaml -s secrets-file.yaml`

Configuration

Authentication options (in order of precedence):

1. Runtime: Pass token when creating client
2. Config file: ~/.config/todoist/config.json with {"api_token": "your_token"}
3. Environment: Set TODOIST_API_TOKEN

Available Tools

Projects

• get_projects - List projects with pagination (limit, cursor)
• get_project - Get single project by ID
• add_project - Create new project

Tasks

• get_tasks - List tasks with pagination and filters
• get_task - Get single task by ID
• add_task - Create new task with all properties
• update_task - Update existing task
• move_task - Move task to different project, section, or parent

Sections (v0.4.0)

• get_sections - List sections for a project with pagination
• get_section - Get single section by ID
• add_section - Create new section in project
• update_section - Update section name
• delete_section - Delete a section

Labels (v0.4.0)

• get_labels - List all labels with pagination
• get_label - Get single label by ID
• add_label - Create new label
• update_label - Update label properties
• delete_label - Delete a label

Batch Operations (v0.4.0)

• batch_move_tasks - Move multiple tasks to project/section
• batch_update_labels - Add/remove labels from multiple tasks
• batch_update_tasks - Update multiple tasks with same properties
• batch_complete_tasks - Complete multiple tasks at once

Comments

• get_comments - List comments for task/project with pagination
• get_comment - Get single comment by ID
• add_comment - Add comment to task or project
• update_comment - Update existing comment
• delete_comment - Delete a comment

Technical Details

• Built with FastMCP v2.3.3+
• Python 3.11+
• Direct API v1 integration using httpx
• No dependency on todoist-api-python SDK

Development

# Clone repository
git clone https://github.com/OAuthBringer/todoist-mcp
cd todoist-mcp

# Create virtual environment
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install dependencies
uv pip install -e .
uv pip install -e ".[dev]"

# Run tests
pytest