Todoist

You can run an MCP server that bridges Claude with Todoist, enabling advanced task, project, section, label, comment, and completed-tasks history operations through a unified API. This extended server uses the latest Todoist API and MCP SDK to deliver robust search, efficient actions, rich responses, and straightforward client integration for powerful workflow automation.

How to use

To use this server, you configure an MCP client (such as Claude Desktop) to connect to one of the supported MCP endpoints exposed by the server. You then issue natural language or structured requests to create, read, update, or move tasks and related entities, as well as retrieve completed tasks history via Todoist REST API v1. The server handles translation between your requests and Todoist API calls, including advanced search, bulk operations, and detailed results.

Client configuration typically involves specifying the MCP server command or URL, and providing authentication or API tokens as needed. The examples below show common ways to run the server locally and connect Claude Desktop to it. Use the method that matches how you install and run the server in your environment.

Configuration examples for Claude Desktop connect your client to the MCP server via a local runtime. You can run the server directly with Node, via npx, or install it globally and reference the executable from Claude.

Below are concrete configuration blocks you can adapt. These blocks assume you have a Todoist API token available and the server is accessible from your environment.

{
  "mcpServers": {
    "todoist-mcp-server": {
      "command": "node",
      "args": ["/path/to/your/todoist-mcp-server-ext/dist/index.js"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

How to install

Prerequisites: you need Node.js and npm installed on your system. You will also need a Todoist API token to access Todoist data.

Step 1: Clone the extended MCP server repository.

Step 2: Install dependencies.

Step 3: Build the project.

Step 4: Run the server using your preferred method (local node execution, npx, or global install) and configure your client to use it.

# Clone the extended repository
git clone https://github.com/kydycode/todoist-mcp-server-ext.git
cd todoist-mcp-server-ext

# Install dependencies
npm install

# Build the project
npm run build

# Example run (node) using a local path to the built index
export TODOIST_API_TOKEN="your_actual_todoist_api_token"
echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | node dist/index.js

Configuration essentials

The extended MCP server supports multiple ways to run and connect. Choose the method that matches your workflow and environment. The server can be started locally with Node, via npx for quick testing, or installed globally for ease of use.

Important: always provide your Todoist API token as an environment variable when starting the server.

Tools and capabilities overview

This server exposes a comprehensive set of operations categorized by entity. You can perform full CRUD-like actions, advanced searches, and bulk operations across tasks, projects, sections, labels, comments, and completed tasks history. Each tool is designed to be called through the MCP interface, returning rich task and metadata details.

Usage notes and tips

Use precise identifiers when performing operations by ID to ensure exact targets. Take advantage of Todoist’s filter-based search for robust query capabilities. When moving tasks, you can relocate them between projects, sections, or convert them into subtasks.

For completed tasks history, use the REST API v1 integration to retrieve data with cursor-based pagination and rich metadata such as labels, priorities, and completion timestamps.

Available tools

todoist_create_task

Create tasks with full options including subtasks, labels, projects, sections, and priorities.

todoist_quick_add_task

Create tasks using Todoist's Quick Add syntax for natural language input.

todoist_get_tasks

Retrieve tasks with filtering (project, section, parent, label, IDs) and pagination.

todoist_get_task

Get a specific task by its ID with detailed information.

todoist_update_task

Update task properties such as content, description, due date, priority, and labels.

todoist_delete_task

Delete a task by its ID.

todoist_complete_task

Mark a task as complete.

todoist_reopen_task

Reopen a completed task.

todoist_search_tasks

Search tasks using Todoist's filter engine.

todoist_move_task

Move a task to a different project, section, or make it a subtask.

todoist_bulk_move_tasks

Move multiple tasks with their subtasks in a single operation.

todoist_get_projects

List all active projects with pagination support.

todoist_get_project

Get a specific project by its ID.

todoist_create_project

Create a new project with properties such as name, color, favorite status, and sub-projects.

todoist_update_project

Update project properties.

todoist_delete_project

Delete a project by its ID.

todoist_get_sections

List sections, either all or within a specific project.

todoist_create_section

Create a section within a project.

todoist_update_section

Update a section's name.

todoist_delete_section

Delete a section by its ID.

todoist_create_label

Create a new label with name, color, and order.

todoist_get_label

Get a specific label by its ID.

todoist_get_labels

List all labels with pagination support.

todoist_update_label

Update an existing label by its ID.

todoist_delete_label

Delete a label by its ID.

todoist_create_comment

Create a new comment on a task or project, with optional attachments.

todoist_get_comment

Get a specific comment by its ID.

todoist_get_comments

Get comments for a task or project with pagination.

todoist_update_comment

Update an existing comment by its ID.

todoist_delete_comment

Delete a comment by its ID.

todoist_get_completed_tasks

Get completed tasks history using Todoist REST API v1 with filtering and cursor pagination.