Todoist MCP

<!-- TODO: redo auth tests and write extensive tests generally --> <!-- TODO: global review & feedback --> <!-- TODO: token refresh functionality --> <!-- TODO: integrate MCP auth spec with todoist oauth api? docs: https://modelcontextprotocol.io/specification/draft/basic/authorization -->

Note: predictably obsoleted by Todoist AI SDK, see here.

---

Connect this Model Context Protocol server to your LLM to interact with Todoist.

Functionality

This integration implements all the APIs available from the Todoist TypeScript Client, providing access to:

Task Management

• Create tasks (with content, descriptions, due dates, priorities, labels, and more)
• Create tasks with natural language (e.g., "Submit report by Friday 5pm #Work")
• Retrieve tasks (individual, filtered, or all tasks)
• Retrieve completed tasks (by completion date or due date)
• Get productivity statistics
• Update tasks
• Move tasks (individually or in batches)
• Close/reopen tasks
• Delete tasks

Project Management

• Create, retrieve, update, and delete projects

Section Management

• Create, retrieve, update, and delete sections within projects

Comment Management

• Add, retrieve, update, and delete comments for tasks or projects

Label Management

• Create, retrieve, update, and delete labels
• Manage shared labels

Collaboration

• Get collaborators for projects

Setup

Build the server app:

bun install
bun run build

Run in development

TODOIST_API_KEY=<key> bun dev

Docker deployment:

docker compose up -d

Debugging:

Use the inspector to debug the server:

bunx @modelcontextprotocol/inspector

Configure Claude:

You must install the Claude desktop app which supports MCP.

You can get your Todoist API key from Todoist > Settings > Integrations > Developer.

Then, in your claude_desktop_config.json, add a new MCP server:

{
    "mcpServers": {
        "default-server": {
            "type": "streamable-http",
            "url": "http://localhost:3000/mcp",
            "note": "For Streamable HTTP connections, add this URL directly in your MCP Client"
        }
    }
}

You can now launch Claude desktop app and ask to update Todoist.

🔐 Security Features

This MCP server has been secured with enterprise-grade security measures:

• Authentication Required: JWT Bearer tokens or API key authentication
• Rate Limiting: Prevents abuse with configurable limits
• Input Validation: Comprehensive request validation and sanitization
• Security Headers: CORS, CSP, HSTS, and other security headers
• Logging & Monitoring: Security event logging and request monitoring
• Environment Configuration: Secure configuration via environment variables

See SECURITY.md for detailed security documentation.

Quick Security Setup

1. Generate secure tokens:

   npm run setup-security
   

2. Create .env file:

   cp .env.example .env
   # Add your generated tokens and Todoist API key
   

3. Required Environment Variables:

   JWT_SECRET=your_generated_jwt_secret_here
   TODOIST_API_KEY=your_todoist_api_key_here
   

Authentication

The server supports two authentication methods:

Method 1: API Key (Recommended for scripts)

curl -X POST http://localhost:3000/mcp \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

Method 2: JWT Bearer Token (Recommended for applications)

curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'