⚠️ ARCHIVED: This project has been retired and is no longer maintained. Reason: Replaced by the official Todoist MCP plugin in the Claude connector registry. Retired: 2026-03-22

Todoist MCP Server

MCP server that connects Claude Desktop, Cowork, and Claude Code to your Todoist account. Full CRUD for tasks, projects, sections, comments, and labels.

Tools (25 total)

Tasks

• todoist_list_tasks — List/filter tasks (by project, section, label, or Todoist filter syntax)
• todoist_get_task — Get a single task by ID
• todoist_create_task — Create with due dates, priority, labels, recurring schedules
• todoist_update_task — Update any task field
• todoist_close_task — Mark complete (advances recurring tasks)
• todoist_reopen_task — Reopen a completed task
• todoist_delete_task — Permanently delete

Projects

• todoist_list_projects / todoist_get_project / todoist_create_project / todoist_update_project / todoist_delete_project

Sections

• todoist_list_sections / todoist_create_section / todoist_update_section / todoist_delete_section

Comments

• todoist_list_comments / todoist_create_comment / todoist_update_comment / todoist_delete_comment

Labels

• todoist_list_labels / todoist_create_label / todoist_update_label / todoist_delete_label

Prerequisites

1. Todoist API Token — Get from: Todoist → Settings → Integrations → Developer
2. Python 3.12+ (for local use) or Docker (for VPS deployment)

Quick Start — Local (stdio)

# Clone and install
git clone https://github.com/alobarquest/todoist-mcp.git
cd todoist-mcp
pip install -r requirements.txt

# Set your token
export TODOIST_API_TOKEN="your_token_here"

# Run (stdio mode for local clients)
python -m src.server

Local Development

Run Tests

pip install -r requirements.txt
python -m pytest tests/ -v

Lint

ruff check src/ tests/

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "todoist": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/todoist-mcp",
      "env": {
        "TODOIST_API_TOKEN": "your_token_here"
      }
    }
  }
}

Claude Code Configuration

Add to your project's .mcp.json or global ~/.claude/settings.json:

{
  "mcpServers": {
    "todoist": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/todoist-mcp",
      "env": {
        "TODOIST_API_TOKEN": "your_token_here"
      }
    }
  }
}

Remote Server (VPS via Coolify)

When deployed to the VPS, the server runs in streamable HTTP mode.

Connect Claude Desktop to the remote server:

{
  "mcpServers": {
    "todoist": {
      "url": "https://todoist-mcp.devonwatkins.com/mcp/"
    }
  }
}

Environment variables for Coolify:

Variable	Description
TODOIST_API_TOKEN	Your Todoist API token (from BWS)
MCP_TRANSPORT	streamable_http (set in Dockerfile)
MCP_PORT	8000 (set in Dockerfile)

Deployment — Coolify/Hetzner VPS

This follows Flavor A from Devon's Infra Standards (lightweight, single container).

However, since we use GHCR image pulls (not source build), the CI/CD follows the Flavor B pattern:

1. Push to main → GitHub Actions builds image → pushes to ghcr.io/alobarquest/todoist-mcp
2. Coolify webhook triggers redeploy → pulls latest image

Coolify Setup

• Build type: Docker Image
• Image: ghcr.io/alobarquest/todoist-mcp:latest
• Port: 8000
• Domain: todoist-mcp.devonwatkins.com
• Health check: http://127.0.0.1:8000/health/ready
• Environment: TODOIST_API_TOKEN from BWS

GitHub Repo Secrets

• COOLIFY_WEBHOOK_URL — Coolify deploy webhook for this resource
• COOLIFY_API_TOKEN — Coolify API bearer token

Health Checks

Two endpoints are available for health monitoring:

• /health/live — Liveness check. Always returns 200 OK. Use to verify the server is running.
• /health/ready — Readiness check. Returns 200 OK if TODOIST_API_TOKEN is set, 503 Service Unavailable otherwise. Use in Coolify health check configuration.

CI/CD

All commits to main are validated by GitHub Actions before deployment:

• Lint: ruff check src/ tests/ — code formatting and style
• Tests: python -m pytest tests/ -v — all tests must pass

The build-and-push job only runs after the validate job passes. PRs are also validated before merging.

Rate Limits

Todoist allows 1000 requests per user per 15 minutes. The server returns a clear error message if you hit this limit.

License

MIT