Shockedrope/todoist-mcp-server

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

1. Install the MCP Python SDK and dependencies:

pip install mcp httpx pydantic

2. Save the server file:

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

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

1. Log in to Todoist
2. Go to Settings → Integrations → Developer
3. Copy your API token
4. 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

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

1. "Invalid API token" error:

   • Verify your token in Todoist Settings → Integrations → Developer
   • Ensure the token is correctly set in the configuration

2. "Resource not found" errors:

   • Check that project/task IDs are correct
   • IDs are now strings in Todoist API v2

3. Rate limit errors:

   • Wait 15 minutes before making more requests
   • Consider batching operations where possible

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

1. Check the Todoist API documentation: https://developer.todoist.com/rest/v2/
2. Review MCP documentation: https://modelcontextprotocol.io/
3. 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