# Todoist MCP Server

A comprehensive Model Context Protocol (MCP) server for the Todoist API. Provides full access to tasks, projects, labels, sections, and comments with support for all task properties including priorities, due dates, labels, subtasks, and more.

## Features

- **Complete Task Management**: Create, read, update, delete, complete, and reopen tasks
- **Full Task Properties Support**: Content, description, due dates (natural language or specific), priority (1-4), labels, duration estimates, subtasks, assignees, and more
- **Project Management**: Create and manage projects with colors, hierarchies, and view styles
- **Label Management**: Create and organize labels for cross-project task categorization
- **Section Management**: Organize tasks within projects using sections
- **Comment Management**: Add and manage comments on tasks and projects
- **Rate Limiting**: Built-in rate limit handling (450 requests per 15 minutes)
- **Error Handling**: Comprehensive error handling with meaningful error messages

## Installation

### Prerequisites

- Node.js (v18 or higher)
- npm
- A Todoist account with API token

### Get Your Todoist API Token

1. Log in to your Todoist account
2. Go to Settings → Integrations → Developer
3. Copy your API token
4. Set it as an environment variable: `TODOIST_API_TOKEN`

### Install the Server

```bash
# Clone or download this repository
cd todoist-mcp

# Install dependencies
npm install

# Build the project
npm run build
```

## Configuration

### For Claude Desktop

Add this to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "todoist": {
      "command": "node",
      "args": [
        "E:\\my drive\\programs and files\\dev\\todoist MCP\\build\\index.js"
      ],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}
```

Replace the path with your actual installation path and add your Todoist API token.

### For Other MCP Clients

Set the `TODOIST_API_TOKEN` environment variable and run:

```bash
node build/index.js
```

## Available Tools

### Task Management

#### `list_tasks`
Get all active tasks with optional filtering.

**Parameters:**
- `project_id` (optional): Filter by project
- `section_id` (optional): Filter by section
- `label` (optional): Filter by label name
- `filter` (optional): Custom filter string (e.g., 'today', 'p1', 'overdue')
- `lang` (optional): Language code for filter parsing

**Example:**
```json
{
  "filter": "today",
  "project_id": "2203306141"
}
```

#### `get_task`
Get a single task by ID with all properties.

**Parameters:**
- `task_id` (required): Task ID

#### `create_task`
Create a new task with comprehensive properties.

**Parameters:**
- `content` (required): Task title
- `description` (optional): Task description
- `project_id` (optional): Project ID
- `section_id` (optional): Section ID
- `parent_id` (optional): Parent task ID for subtasks
- `priority` (optional): 1-4, where 4 is urgent
- `labels` (optional): Array of label names
- `due_string` (optional): Natural language due date (e.g., "tomorrow at 14:00")
- `due_date` (optional): YYYY-MM-DD format
- `due_datetime` (optional): RFC3339 format
- `due_lang` (optional): Language for parsing due_string
- `assignee_id` (optional): User ID to assign
- `duration` (optional): Duration amount
- `duration_unit` (optional): "minute" or "day"

**Example:**
```json
{
  "content": "Buy groceries",
  "description": "Milk, eggs, bread",
  "priority": 3,
  "labels": ["shopping", "urgent"],
  "due_string": "tomorrow at 14:00"
}
```

#### `update_task`
Update an existing task.

**Parameters:**
- `task_id` (required): Task ID
- All other parameters from `create_task` (optional)

#### `complete_task`
Mark a task as complete. Recurring tasks move to next occurrence.

**Parameters:**
- `task_id` (required): Task ID

#### `reopen_task`
Reopen a completed task.

**Parameters:**
- `task_id` (required): Task ID

#### `delete_task`
Permanently delete a task.

**Parameters:**
- `task_id` (required): Task ID

### Project Management

#### `list_projects`
Get all projects.

#### `get_project`
Get a single project by ID.

**Parameters:**
- `project_id` (required): Project ID

#### `create_project`
Create a new project.

**Parameters:**
- `name` (required): Project name
- `parent_id` (optional): Parent project ID for nested projects
- `color` (optional): Color name (e.g., "blue", "red")
- `is_favorite` (optional): Boolean
- `view_style` (optional): "list" or "board"

#### `update_project`
Update an existing project.

**Parameters:**
- `project_id` (required): Project ID
- All other parameters from `create_project` (optional)

#### `delete_project`
Permanently delete a project and all its tasks.

**Parameters:**
- `project_id` (required): Project ID

### Label Management

#### `list_labels`
Get all labels.

#### `get_label`
Get a single label by ID.

**Parameters:**
- `label_id` (required): Label ID

#### `create_label`
Create a new label.

**Parameters:**
- `name` (required): Label name
- `color` (optional): Color name
- `order` (optional): Position in list
- `is_favorite` (optional): Boolean

#### `update_label`
Update an existing label.

**Parameters:**
- `label_id` (required): Label ID
- All other parameters from `create_label` (optional)

#### `delete_label`
Permanently delete a label.

**Parameters:**
- `label_id` (required): Label ID

### Section Management

#### `list_sections`
Get all sections, optionally filtered by project.

**Parameters:**
- `project_id` (optional): Project ID

#### `get_section`
Get a single section by ID.

**Parameters:**
- `section_id` (required): Section ID

#### `create_section`
Create a new section.

**Parameters:**
- `name` (required): Section name
- `project_id` (required): Project ID
- `order` (optional): Position in project

#### `update_section`
Update an existing section.

**Parameters:**
- `section_id` (required): Section ID
- `name` (required): New section name

#### `delete_section`
Delete a section (tasks are not deleted).

**Parameters:**
- `section_id` (required): Section ID

### Comment Management

#### `list_comments`
Get comments for a task or project.

**Parameters:**
- `task_id` (optional): Task ID
- `project_id` (optional): Project ID

#### `get_comment`
Get a single comment by ID.

**Parameters:**
- `comment_id` (required): Comment ID

#### `create_comment`
Create a new comment.

**Parameters:**
- `content` (required): Comment text
- `task_id` (optional): Task ID
- `project_id` (optional): Project ID
- `attachment` (optional): File attachment object

#### `update_comment`
Update an existing comment.

**Parameters:**
- `comment_id` (required): Comment ID
- `content` (required): Updated comment text

#### `delete_comment`
Permanently delete a comment.

**Parameters:**
- `comment_id` (required): Comment ID

## Development

```bash
# Watch mode for development
npm run watch

# Build
npm run build
```

## Rate Limits

The Todoist API has the following rate limits:
- 450 requests per 15 minutes per user

The server automatically tracks requests and throws an error if the limit is exceeded.

## Error Handling

All tools provide meaningful error messages when operations fail. Common errors include:

- Missing or invalid API token
- Rate limit exceeded
- Invalid task/project/label IDs
- Invalid parameter values

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## API Version

This server uses Todoist REST API v2.

## Acknowledgments

Built using the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk) and the [Todoist REST API](https://developer.todoist.com/rest/v2/).