Todoist MCP server for AI agents

The Todoist MCP server is an integration that allows Claude to manage your Todoist tasks and projects through natural language. This powerful connection enables complete task management directly through Claude, giving you a conversational interface to your productivity system.

Installation & Setup

Getting Your Todoist API Token

Log in to your Todoist account
Go to Settings → Integrations
Scroll down to the Developer section
Copy your API token (keep this secure!)

Option 1: Using npx (Recommended)

This method doesn't require installing anything globally.

Configure Claude Desktop

Add the server to your Claude Desktop configuration file:

On macOS/Linux:

File location: ~/.config/claude_desktop_config.json

On Windows:

File location: %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["@greirson/mcp-todoist"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

⚠️ Important: Replace your_api_token_here with your actual Todoist API token.

Option 2: Global npm Installation

If you prefer to install the package globally:

npm install -g @greirson/mcp-todoist

Then configure Claude Desktop:

{
  "mcpServers": {
    "todoist": {
      "command": "mcp-todoist",
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Automatic Installation via Smithery

To install mcp-todoist automatically:

npx -y @smithery/cli install @greirson/mcp-todoist --client claude

Finishing Setup

Restart Claude Desktop
Verify the installation by asking Claude: "Show me my Todoist projects"

Tools Overview

Task Management

Create tasks with full attribute support
Retrieve and filter tasks
Update existing tasks
Mark tasks as complete
Remove tasks

Subtask Management

Create subtasks under parent tasks
Create multiple subtasks efficiently
Convert existing tasks to subtasks
Promote subtasks to main tasks
View task hierarchies with completion tracking

Bulk Task Operations

Create multiple tasks at once
Update multiple tasks based on search criteria
Delete multiple tasks based on search criteria
Complete multiple tasks based on search criteria

Comment Management

Add comments to tasks with optional file attachments
Retrieve comments for tasks or projects

Label Management

List all labels with their IDs and colors
Create new labels with optional color and ordering
Update existing labels
Remove labels from your workspace
Get detailed usage statistics for all labels

Project Management

Create new projects with optional color and favorite status
List all projects with their IDs and names

Section Management

Create sections within projects
List sections within projects

Usage Examples

Project & Section Management

"Show me all my projects"
"Create a new project called 'Work Tasks'"
"Create a section called 'In Progress' in project 12345"
"Show me sections in the Work Tasks project"

Task Creation & Management

"Create task 'Team Meeting' in project 12345"
"Add task 'Review PR' due tomorrow with labels ['Code Review', 'Urgent']"
"Create high priority task with deadline 2024-12-25"
"Update meeting task to be in section 67890"
"Mark the PR review task as complete"

# Task identification by ID (more reliable than name search)
"Get task with ID 1234567890"
"Update task ID 1234567890 to priority 4"
"Complete task with ID 1234567890"
"Delete task ID 1234567890"

Subtask Management

"Create subtask 'Prepare agenda' under task 'Team Meeting'"
"Create multiple subtasks for 'Launch Project': 'Design UI', 'Write tests', 'Deploy'"
"Convert task 'Code Review' to a subtask of 'Release v2.0'"
"Promote subtask 'Bug Fix' to a main task"
"Show me the task hierarchy for 'Launch Project' with completion tracking"

Bulk Operations

"Create multiple tasks for project launch: 'Design mockups', 'Write documentation', 'Set up CI/CD'"
"Update all high priority tasks to be due next week"
"Complete all tasks containing 'review' in project 12345"
"Delete all tasks with priority 1 that are overdue"

Comment Management

"Add comment 'This needs urgent attention' to task 'Review PR'"
"Add comment with attachment to task 67890"
"Show all comments for task 'Team Meeting'"
"Get comments for project 12345"

Label Management

"Show me all my labels"
"Create a new label called 'Urgent' with red color"
"Update the 'Work' label to be blue and mark as favorite"
"Delete the unused 'Old Project' label"
"Get usage statistics for all my labels"

Getting Started Workflow

First Steps

"Test my Todoist connection"
"Show me all my Todoist projects"
"Create a new project called 'Claude Integration Test'"

Basic Task Management

"Create a task 'Try out MCP integration' in my Inbox"
"Add a high priority task 'Review project setup' due tomorrow"
"Show me all my tasks"

Advanced Organization

"Create a section called 'In Progress' in my work project"
"Move the setup task to the In Progress section"
"Add a comment 'This is working great!' to my test task"

Bulk Operations

"Create multiple tasks: 'Plan meeting agenda', 'Prepare slides', 'Send invites'"
"Complete all tasks containing 'test' in the Claude project"
"Update all high priority tasks to be due next week"

Troubleshooting

Common Issues

"No Todoist projects found" or connection errors:

Verify your API token is correct
Check that the token is properly set in your claude_desktop_config.json
Ensure there are no extra spaces or quotes around your token

MCP server not loading:

Confirm the package is installed globally: npm list -g @greirson/mcp-todoist
Restart Claude Desktop completely
Check the configuration file path is correct for your operating system
Try the full path to the mcp-todoist binary: /Users/USERNAME/.npm-global/bin/mcp-todoist

Permission errors:

On macOS/Linux, you may need to create the config directory: mkdir -p ~/.config
Ensure Claude Desktop has permission to read the config file

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "todoist" '{"command":"npx","args":["@greirson/mcp-todoist"],"env":{"TODOIST_API_TOKEN":"your_api_token_here"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "todoist": {
            "command": "npx",
            "args": [
                "@greirson/mcp-todoist"
            ],
            "env": {
                "TODOIST_API_TOKEN": "your_api_token_here"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "todoist": {
            "command": "npx",
            "args": [
                "@greirson/mcp-todoist"
            ],
            "env": {
                "TODOIST_API_TOKEN": "your_api_token_here"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect