home / mcp / todoist mcp server

Todoist MCP Server

Provides MCP access to Todoist projects and tasks with create, read, update, delete, and task completion features.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "angdrew-todoist-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@angdrew/todoist-mcp-server"
      ],
      "env": {
        "TODOIST_API_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}

You can use this MCP server to manage Todoist projects and tasks through a standardized MCP interface. It exposes create, read, update, and delete operations for projects, along with full task management including completion and reopening, all accessible via your MCP client.

How to use

You interact with the Todoist MCP Server through an MCP client. Once the server is running, you can perform the following core actions: create, get, list, update, and delete projects; create, get, list, update, complete, reopen, and delete tasks. You can filter task listings by project, label, or a filter expression to focus on what you need. Use natural language style commands in your MCP client to trigger these endpoints, and rely on the client to present results from Todoist.

How to install

Prerequisites you need before installing: Node.js 18 or newer, npm or yarn, and a Todoist API token.

Step 1: Install dependencies on your machine.

npm install

Step 2: Obtain your Todoist API token from Todoist Integrations and keep it available for configuration.

Step 3: Set the environment variable for the Todoist API token.

export TODOIST_API_TOKEN=your_token_here

Step 4: Build and run the server. You can build, start, or run in development/watch mode as shown below.

# Build the TypeScript code
npm run build

# Run the server
npm start

# Or build and run in one command
npm run dev

# For development with auto-rebuild
npm run watch

Configuration and security

Configure your Claude Desktop client to access the MCP server by adding a dedicated mcpServer entry. The following example shows how to point Claude Desktop at the local MCP server using npx to load the package.

For macOS users, place the configuration file at: ~/Library/Application Support/Claude/claude_desktop_config.json

For Windows users, place the configuration file at: %APPDATA%\\Claude\\claude_desktop_config.json

{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["-y", "@angdrew/todoist-mcp-server"],
      "env": {
        "TODOIST_API_TOKEN": "your_token_here"
      }
    }
  }
}

Error handling

The server provides clear errors for common issues such as invalid API tokens, missing required parameters, API rate limits, and network problems. If an operation cannot be completed, you will receive a descriptive error indicating the cause and guidance to resolve it.

Notes and troubleshooting

Ensure your Todoist API token remains secure. If you rotate tokens, update the environment variable accordingly and restart the MCP server to apply changes.

Available tools

create_project

Create a new project with optional color, viewStyle, parentId, and isFavorite settings.

get_project

Retrieve details for a specific project by its ID.

list_projects

List all projects without requiring parameters.

update_project

Update properties of an existing project, such as name, color, viewStyle, and isFavorite.

delete_project

Remove a project by its ID.

create_task

Create a new task with content, optional description, project association, due date, priority, and labels.

get_task

Retrieve details for a specific task by its ID.

list_tasks

List tasks with optional filtering by project, label, or a filter expression.

update_task

Update task properties including content, description, due dates, priority, and labels.

complete_task

Mark a task as completed.

reopen_task

Reopen a completed task.

delete_task

Delete a task by its ID.