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

# 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

{
  "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:

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:

{
  "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:

{
  "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

# 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 and the Todoist REST API.