Todoist MCP Server

A Model Context Protocol (MCP) server that provides complete CRUD operations for Todoist tasks, projects, comments, and labels.

Purpose

This MCP server provides a secure interface for AI assistants to manage your Todoist tasks, projects, and more through natural language commands. It wraps the Todoist REST API v2 in a secure, Docker-based MCP server.

Features

Task Management (CRUD)

• create_task - Create new tasks with content, description, due dates, priority, and labels
• list_tasks - List all tasks with optional filtering by project, label, or custom filter
• get_task - Get detailed information about a specific task
• update_task - Update task content, description, due date, priority, or labels
• complete_task - Mark a task as completed
• reopen_task - Reopen a completed task
• delete_task - Permanently delete a task

Project Management (CRUD)

• create_project - Create new projects with name, color, favorite status, and view style
• list_projects - List all projects in your account
• get_project - Get detailed information about a specific project
• update_project - Update project name, color, favorite status, or view style
• delete_project - Permanently delete a project

Comment Operations

• create_comment - Add comments to tasks
• list_comments - List all comments for a task or project

Label Operations

• create_label - Create new labels with name and color
• list_labels - List all labels in your account

Prerequisites

• Docker Desktop with MCP Toolkit enabled
• Docker MCP CLI plugin (docker mcp command)
• Todoist account with API token

Getting Your Todoist API Token

1. Go to https://app.todoist.com/app/settings/integrations/developer
2. Scroll down to find "API token"
3. Copy the 40-character hexadecimal token
4. Keep this token secure - it provides full access to your Todoist account

Installation

See the step-by-step instructions provided with the files.

Usage Examples

In Claude Desktop, you can ask:

Tasks

• "Create a task 'Buy groceries' due tomorrow with priority 2"
• "List all my tasks"
• "Show me tasks in project 12345"
• "Complete task 98765"
• "Update task 12345 to have priority 4 and due date 'next Monday'"
• "Delete task 98765"

Projects

• "Create a new project called 'Work Projects' with color blue"
• "List all my projects"
• "Update project 12345 to be a favorite"
• "Delete project 67890"

Comments & Labels

• "Add a comment 'Need to review this' to task 12345"
• "List comments for task 12345"
• "Create a label 'urgent' with color red"
• "Show me all my labels"

Architecture

Claude Desktop → MCP Gateway → Todoist MCP Server → Todoist REST API v2
                                ↓
                    Docker Desktop Secrets
                    (TODOIST_API_TOKEN)

Development

Local Testing

# Set environment variable for testing
export TODOIST_API_TOKEN="your-api-token"

# Run directly
python todoist_server.py

# Test MCP protocol
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python todoist_server.py

Adding New Tools

1. Add the function to todoist_server.py
2. Decorate with @mcp.tool()
3. Update the catalog entry with the new tool name
4. Rebuild the Docker image

Troubleshooting

Tools Not Appearing

• Verify Docker image built successfully: docker images | grep todoist-mcp-server
• Check catalog and registry files
• Ensure Claude Desktop config includes custom catalog
• Restart Claude Desktop

Authentication Errors

• Verify API token with docker mcp secret list
• Ensure secret name is exactly TODOIST_API_TOKEN
• Test token at https://developer.todoist.com/rest/v2/

API Rate Limits

• Todoist allows 1000 requests per 15 minutes per user
• If you hit limits, wait 15 minutes before retrying

Security Considerations

• All credentials stored in Docker Desktop secrets
• Never hardcode API tokens
• Running as non-root user
• API tokens never logged
• All communication over HTTPS

API Reference

This server uses Todoist REST API v2:

• Documentation: https://developer.todoist.com/rest/v2/
• Base URL: https://api.todoist.com/rest/v2

License

Apache 2.0