Todoist MCP Server

# 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 ```bash # 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](LICENSE)