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