# 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](https://github.com/Doist/todoist-ai)._

---

Connect this [Model Context Protocol](https://modelcontextprotocol.io/introduction) server to your LLM to interact with Todoist.

## Functionality

This integration implements all the APIs available from the [Todoist TypeScript Client](https://doist.github.io/todoist-api-typescript/api/classes/TodoistApi/), 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](https://claude.ai/) desktop app which supports MCP.

You can get your Todoist API key from [Todoist > Settings > Integrations > Developer](https://app.todoist.com/app/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](./SECURITY.md) for detailed security documentation.**

## Quick Security Setup

1. **Generate secure tokens:**

   ```bash
   npm run setup-security
   ```

2. **Create `.env` file:**

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

3. **Required Environment Variables:**

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

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

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