Todoist MCP Server

Self-hosted Todoist MCP server running on todoist.backman.design. Wraps the official @doist/todoist-ai package (~35 built-in tools) with a custom Express server for adding your own tools on top. Fronted by Caddy for automatic TLS.

Prerequisites

• Docker & Docker Compose

• A domain with DNS pointed to your server (todoist.backman.design)

• A Todoist API key

Setup

git clone <repo-url> && cd todoist-mcp
cp .env.example .env        # add your Todoist API key
docker compose up -d

Caddy automatically provisions TLS certificates via Let's Encrypt. Make sure ports 80 and 443 are open and DNS is pointed before starting.

Connecting clients

Claude Code

claude mcp add --transport http todoist https://todoist.backman.design/mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "todoist": {
      "type": "http",
      "url": "https://todoist.backman.design/mcp"
    }
  }
}

Cursor / VS Code

Add to MCP settings (.cursor/mcp.json or VS Code MCP config):

{
  "servers": {
    "todoist": {
      "type": "http",
      "url": "https://todoist.backman.design/mcp"
    }
  }
}

Updating

Rebuild to pull the latest @doist/todoist-ai version:

docker compose build --no-cache && docker compose up -d

To pin a specific version, edit the version in package.json and rebuild.

Troubleshooting

Check logs:

docker compose logs mcp-server
docker compose logs caddy

Health check:

curl https://todoist.backman.design/health

Certificate issues: Caddy handles certs automatically. If provisioning fails, ensure ports 80/443 are reachable and DNS resolves correctly. Check Caddy logs for details.

Architecture

Client (Claude Code, etc.)
  │
  │  HTTPS
  ▼
┌─────────────────────┐
│  Caddy (TLS + proxy)│  :443
│  caddy:2-alpine     │
└────────┬────────────┘
         │  HTTP
         ▼
┌─────────────────────┐
│  MCP Server         │  :3001
│  server.js          │
│  ├ @doist/todoist-ai│
│  └ custom tools     │
└────────┬────────────┘
         │
         ▼
    Todoist API