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

Related MCP server: Todoist MCP Server

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

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/