<p align="center"> <img src="docs/logo.svg" width="120" alt="Todoist MCP logo"> </p>

Todoist MCP Server

A specialized Model Context Protocol (MCP) server for Todoist task management. This Docker-based server enables Claude Desktop and other MCP clients to interact with Todoist for creating, updating, and querying tasks.

Features

• Task Management: Create, update, complete, and delete tasks
• Smart Queries: Get tasks by project, label, priority, or filter
• Project & Label Management: Organize your tasks efficiently
• Redis Caching: Optional caching for improved performance
• Docker Support: Easy deployment with Docker and Docker Compose

Prerequisites

• Docker and Docker Compose (for containerized deployment)
• Todoist Account: Sign up for Todoist
• Todoist API Token: Get your token from Todoist Integration Settings
• Claude Desktop (optional): For MCP client integration

Quick Start

1. Clone and Configure

cd todoist-mcp
cp .env.example .env.local

Edit .env.local and add your Todoist API token:

TODOIST_API_TOKEN=your-todoist-api-token-here
DEBUG=false

# Optional Redis caching
REDIS_HOST=
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_USE_SSL=false

2. Run with Docker Compose

docker-compose up --build

The server will start in stdio mode, ready to accept MCP connections.

3. Connect to Claude Desktop

Add this configuration to your Claude Desktop config file:

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

{
  "mcpServers": {
    "todoist": {
      "command": "docker",
      "args": ["compose", "-f", "/path/to/todoist-mcp/docker-compose.yml", "run", "--rm", "todoist-mcp"]
    }
  }
}

Restart Claude Desktop to activate the server.

Configuration

Environment Variables

Variable	Required	Default	Description
TODOIST_API_TOKEN	Yes	-	Your Todoist API token
DEBUG	No	false	Enable debug logging
REDIS_HOST	No	-	Redis server hostname (for caching)
REDIS_PORT	No	6379	Redis server port
REDIS_PASSWORD	No	-	Redis password
REDIS_USE_SSL	No	false	Use SSL for Redis connection

Available MCP Tools

The Todoist MCP server provides the following tools:

Task Operations

• create_task - Create a new task
• update_task - Update an existing task
• complete_task - Mark a task as complete
• delete_task - Delete a task
• uncomplete_task - Reopen a completed task

Task Queries

• get_tasks_today - Get all tasks due today
• get_overdue_tasks - Get all overdue tasks
• get_tasks_by_project - Get tasks from a specific project
• get_tasks_by_label - Get tasks with a specific label
• get_tasks_by_priority - Get tasks by priority level
• get_tasks_by_filter - Query tasks using Todoist filter syntax

Project Management

• get_projects - List all projects
• create_project - Create a new project
• update_project - Update a project
• delete_project - Delete a project

Label Management

• get_labels - List all labels
• create_label - Create a new label
• update_label - Update a label
• delete_label - Delete a label

Server Management

• get_server_status - Check server health
• get_server_config - View server configuration
• get_cache_stats - View cache performance metrics
• clear_cache - Clear cached data
• get_cache_info - View Redis server information

Local Development

Without Docker

1. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install dependencies:

pip install -r requirements.txt

3. Set environment variables:

export TODOIST_API_TOKEN=your-api-token

4. Run the server:

python server.py

With Docker

Build and run:

docker build -t todoist-mcp .
docker run -e TODOIST_API_TOKEN=your-token todoist-mcp

Testing

Test Server Status

You can test the server by connecting via Claude Desktop and asking:

"What's the status of my Todoist server?"

Test Task Operations

"Create a task called 'Test task' in my Inbox" "Show me all tasks due today" "Mark task ID 12345 as complete"

Troubleshooting

"Todoist API token not configured"

Solution: Ensure TODOIST_API_TOKEN is set in your .env.local file or environment variables.

Connection Issues

Solution:

• Verify your API token is correct
• Check your internet connection
• Ensure Docker container has network access

Cache Not Working

Solution:

• Verify Redis connection settings
• Ensure Redis server is running
• Check Redis credentials and SSL settings

Architecture

The Todoist MCP server follows this architecture:

Claude Desktop
     ↓ (stdio)
Docker Container
     ↓
MCP Server (FastMCP)
     ↓
Todoist Service
     ↓
Todoist API

Optional Redis caching layer improves performance by reducing API calls.

Security Notes

• Never commit your .env.local file or API tokens to version control
• Use environment-specific .env files
• Consider using Docker secrets for production deployments
• API tokens are never exposed through MCP tool responses

License

This project is provided as-is for personal use.

Support

For Todoist API documentation, visit: https://developer.todoist.com/