Todoist

You can run a Todoist MCP Server to let Claude interact with your Todoist tasks and projects through a dedicated MCP interface. This server supports creating, listing, updating, completing tasks, managing projects, labels, and natural language dates, with built-in error handling and rate limiting to stay within API boundaries.

How to use

To use this MCP server, you connect an MCP client (such as Claude) to the local or remote MCP endpoint exposed by the server. You can create tasks, list tasks with filters, update task properties, complete tasks, and search or manage projects and labels. The tools are designed to be intuitive and to respect Todoist semantics like due dates (including natural language parsing) and priorities.

How to install

Follow these steps to install and run the Todoist MCP Server locally.

Prerequisites you need before starting:

From source and initial setup

# Clone the repository
git clone <your-repo-url>
cd todoist-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configure your API token and client

Obtain a Todoist API token and set it up in the environment used by the MCP server.

Create or copy the environment file and insert your token.

cp .env.example .env

TODOIST_API_TOKEN=your_actual_token_here
LOG_LEVEL=error

Configure Claude Desktop to start the MCP server

Add the MCP server configuration to Claude Desktop so you can connect to the local server.

Configuration location varies by OS. Use the absolute path to make sure Claude Desktop can locate the server.

{
  "mcpServers": {
    "todoist": {
      "command": "node",
      "args": ["/absolute/path/to/todoist-mcp/build/server.js"],
      "env": {
        "TODOIST_API_TOKEN": "your_actual_token_here"
      }
    }
  }
}

Start and test the server

Restart Claude Desktop after updating the configuration to apply the changes.

Then you can issue tasks or queries to the MCP server from Claude using the available tools.

Usage patterns and practical tips

Use the Create Task tool to add new tasks with optional project, due date, priority, labels, and subtasks. Use List Tasks with filters to focus on specific projects, sections, or labels. Update Task and Complete Task to manage progress. Use Search Tasks to quickly locate items by content or description. You can also list all projects to navigate Todoist structure and review labels and priorities for consistent tagging.

Available tools overview

The following tools are exposed by the MCP server to manage Todoist data.

Rate limits and error handling

The server respects Todoist API rate limits. When limits are exceeded, you will receive a 429 error that is handled, and you can retry after waiting.

All errors return descriptive messages, including invalid API tokens, missing task IDs, rate limit exceeded, network errors, and validation issues.

Natural language date parsing and inputs

The server supports natural language date parsing for deadlines using phrases like tomorrow, next Monday, every Friday, in 3 days, next week, or specific dates like Dec 25. You can also use standard date formats like 2024-12-31 or 2024-12-31T14:30:00.

Available tools

todoist_create_task

Create a new task with optional project, due date, priority, labels, and parent task for subtasks.

todoist_list_tasks

List active tasks with optional filters for project, section, label, or custom Todoist filter.

todoist_get_task

Get detailed information about a specific task including all metadata.

todoist_update_task

Update an existing task with new content, description, due date, priority, or labels.

todoist_complete_task

Mark a task as completed.

todoist_list_projects

List all projects in Todoist, including inbox and shared projects.

todoist_search_tasks

Search for tasks by text in their content or description.