# Todoist MCP Server

Self-hosted Todoist MCP server running on `todoist.backman.design`. Wraps the official [`@doist/todoist-ai`](https://github.com/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](https://todoist.com/help/articles/find-your-api-token-Jpzx9IIlB)

## Setup

```bash
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

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

### Claude Desktop

Add to `claude_desktop_config.json`:

```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):

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

## Updating

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

```bash
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:**

```bash
docker compose logs mcp-server
docker compose logs caddy
```

**Health check:**

```bash
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
```