Todoist MCP Server

A comprehensive Model Context Protocol (MCP) server for Todoist that enables AI assistants to manage tasks, projects, labels, sections, and comments through natural conversation.

Features

The Todoist MCP server provides full task management capabilities:

📁 Project Management

List Projects - View all projects with hierarchy, colors, and metadata
Create Projects - Add new projects with customization options
Update Projects - Modify project properties like name, color, and view style

✅ Task Operations

List Tasks - View tasks with filters (by project, label, or Todoist filters)
Create Tasks - Add tasks with full control over properties
Quick Add Tasks - Use natural language to create tasks
Update Tasks - Modify task content, due dates, priorities, and labels
Complete Tasks - Mark tasks as done (handles recurring tasks automatically)

📑 Organization

Sections - List and create sections to organize tasks within projects
Labels - Manage personal labels for task categorization
Comments - Add and view comments on tasks and projects

Installation

Prerequisites

Python 3.9 or higher
A Todoist account with API access
Your Todoist API token (found in Settings → Integrations → Developer)

Setup

Install the MCP Python SDK and dependencies:

pip install mcp httpx pydantic

Save the server file:

Save todoist_mcp.py to a location on your system (e.g., ~/mcp-servers/todoist/)

Make it executable:

chmod +x todoist_mcp.py

Configuration

For Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "todoist": {
      "command": "python",
      "args": ["/path/to/todoist_mcp.py"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Replace:

/path/to/todoist_mcp.py with the actual path to your server file
your_api_token_here with your Todoist API token

Getting Your Todoist API Token

Log in to Todoist
Go to Settings → Integrations → Developer
Copy your API token
Keep it secure - this token provides full access to your Todoist account

Usage Examples

Once configured, you can interact with Todoist through natural language:

Project Management

"Show me all my Todoist projects"
"Create a new project called 'Q1 Goals' with red color"
"Make my Work project a favorite"
"Change my Personal project to board view"

Task Management

"What tasks do I have due today?"
"Create a task 'Review quarterly report' in my Work project due tomorrow with high priority"
"Add task 'Call dentist next Monday at 2pm #Health p2'" (uses Quick Add)
"Mark task 123456 as complete"
"Update my 'Buy milk' task to be due tomorrow"
"Show me all tasks with the label 'urgent'"
"List tasks in my Work project"

Organization

"Create a section called 'In Progress' in my Work project"
"Show me all my labels"
"Create a new label called 'waiting' with blue color"
"Add a comment 'Started working on this' to task 789012"

Natural Language Quick Add

The Quick Add feature understands:

Projects: @ProjectName or #ProjectName
Labels: @LabelName
Priority: p1, p2, p3, p4 or !, !!, !!!
Due dates: today, tomorrow, next Monday, Jan 15, etc.

Examples:

"Meeting tomorrow at 3pm #Work p2"
"Buy groceries today @Shopping"
"Review document every Friday #Work"

Available Tools

Tool	Description
`todoist_list_projects`	List all projects with hierarchy and metadata
`todoist_create_project`	Create a new project
`todoist_update_project`	Update project properties
`todoist_list_tasks`	List tasks with optional filters
`todoist_create_task`	Create a task with full control
`todoist_quick_add_task`	Add task using natural language
`todoist_update_task`	Update task properties
`todoist_complete_task`	Mark task as complete
`todoist_list_sections`	List project sections
`todoist_create_section`	Create a new section
`todoist_list_labels`	List personal labels
`todoist_create_label`	Create a new label
`todoist_get_comments`	Get comments for task/project
`todoist_add_comment`	Add a comment

Response Formats

Most tools support two response formats:

Markdown (default): Human-readable formatted text with emojis and structure
JSON: Machine-readable format with complete data

The server automatically uses the appropriate format based on context.

Rate Limits

Todoist API has the following limits:

Maximum 1000 requests per 15 minutes per user
1 MB maximum request body size
15 second processing timeout per request

The server provides clear error messages when limits are exceeded.

Error Handling

The server provides clear, actionable error messages:

Invalid API token errors with setup guidance
Rate limit notifications with wait recommendations
Resource not found errors with ID verification hints
Network timeout handling with retry suggestions

Security Notes

Store your API token securely - never commit it to version control
The API token provides full access to your Todoist account
Use environment variables for token storage
Consider using a separate Todoist account for testing

Troubleshooting

Common Issues

"Invalid API token" error:
- Verify your token in Todoist Settings → Integrations → Developer
- Ensure the token is correctly set in the configuration
"Resource not found" errors:
- Check that project/task IDs are correct
- IDs are now strings in Todoist API v2
Rate limit errors:
- Wait 15 minutes before making more requests
- Consider batching operations where possible
Connection timeouts:
- Check your internet connection
- Todoist API may be temporarily unavailable

Debug Mode

To see detailed error messages, run the server directly:

TODOIST_API_TOKEN=your_token python todoist_mcp.py

Development

Adding New Features

The server is built with FastMCP and follows MCP best practices:

Pydantic models for input validation
Comprehensive error handling
Support for both Markdown and JSON responses
Character limit handling for large responses

Code Structure

Pydantic Models: Input validation for all operations
Utility Functions: Shared API requests, error handling, formatting
Tool Definitions: Each tool with comprehensive docstrings
Response Formatting: Markdown and JSON output options

License

MIT License - See LICENSE file for details

Support

For issues or questions:

Check the Todoist API documentation: https://developer.todoist.com/rest/v2/
Review MCP documentation: https://modelcontextprotocol.io/
File an issue on the project repository

Changelog

Version 1.0.0 (Initial Release)

Complete project management (list, create, update)
Full task operations (CRUD, complete, quick add)
Section and label management
Comment system support
Natural language task creation
Comprehensive error handling
Support for all Todoist filters
Markdown and JSON response formats