# todoist-mcp

An MCP (Model Context Protocol) server for Todoist that gives AI assistants full access to your tasks, projects, labels, filters, comments, and more.

Built on the official [`@doist/todoist-ai`](https://www.npmjs.com/package/@doist/todoist-ai) package.

## Tools

### Tasks

| Tool | Description |
|------|-------------|
| `add-tasks` | Create one or more tasks |
| `find-tasks` | Search and filter tasks |
| `find-tasks-by-date` | Find tasks by due date or date range |
| `find-completed-tasks` | Find previously completed tasks |
| `update-tasks` | Update existing tasks |
| `complete-tasks` | Mark tasks as complete |
| `uncomplete-tasks` | Reopen completed tasks |
| `reschedule-tasks` | Change task due dates |

### Projects

| Tool | Description |
|------|-------------|
| `add-projects` | Create new projects |
| `find-projects` | Search and list projects |
| `update-projects` | Update project properties |
| `project-management` | Archive or unarchive projects |
| `project-move` | Move projects between workspaces |

### Sections

| Tool | Description |
|------|-------------|
| `add-sections` | Create sections within projects |
| `find-sections` | Search and list sections |
| `update-sections` | Update section properties |

### Comments

| Tool | Description |
|------|-------------|
| `add-comments` | Add comments to tasks or projects |
| `find-comments` | Search and list comments |
| `update-comments` | Update existing comments |
| `view-attachment` | View file attachments on comments |

### Labels

| Tool | Description |
|------|-------------|
| `add-labels` | Create new labels |
| `find-labels` | Search and list labels |

### Filters

| Tool | Description |
|------|-------------|
| `add-filters` | Create saved filters |
| `find-filters` | Search and list filters |
| `update-filters` | Update existing filters |

### Collaboration

| Tool | Description |
|------|-------------|
| `find-project-collaborators` | List collaborators on a project |
| `manage-assignments` | Assign or unassign tasks |
| `list-workspaces` | List available workspaces |

### General

| Tool | Description |
|------|-------------|
| `get-overview` | Get a summary of your Todoist account |
| `search` | Full-text search across Todoist |
| `fetch` | Fetch a Todoist URL |
| `fetch-object` | Fetch a specific task, project, section, or comment by ID |
| `delete-object` | Delete a task, project, section, label, or other object |
| `reorder-objects` | Reorder tasks, projects, or sections |
| `find-activity` | View activity/audit log |
| `get-productivity-stats` | Get your productivity statistics |
| `user-info` | Get current user information |

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `TODOIST_API_KEY` | Yes | Your Todoist API token (get it from [Settings > Integrations > Developer](https://todoist.com/app/settings/integrations/developer)) |

## Installation

```bash
npm ci
```

## Usage

### Stdio mode (for Claude Desktop, etc.)

```bash
TODOIST_API_KEY=your_api_key node dist/main.js
```

Or create a `.env` file with your API key:

```
TODOIST_API_KEY=your_api_key
```

Then run:

```bash
node dist/main.js
```

### HTTP mode (standalone server)

```bash
TODOIST_API_KEY=your_api_key node dist/main-http.js
```

The server starts on port 3000 by default (set `PORT` to override). The MCP endpoint is at `/mcp` and a health check is at `/health`.

### HTTP mode with mcp-proxy

```bash
mcp-proxy --port 8006 -- node dist/main.js
```

### Claude Desktop configuration

Add to your Claude Desktop MCP config:

```json
{
  "mcpServers": {
    "todoist": {
      "command": "node",
      "args": ["/path/to/todoist-mcp/dist/main.js"],
      "env": {
        "TODOIST_API_KEY": "your_api_key"
      }
    }
  }
}
```

## License

MIT