Todoist MCP server

This MCP Todoist server enables Claude to interact with your Todoist account, allowing you to manage tasks, projects, and labels directly through the Claude Desktop interface.

Installation and Setup

Prerequisites

• Python 3.11+
• Astral UV
• Todoist account and API token
• Claude Desktop

Installation

Install the MCP server using UV:

uvx mcp-todoist

Configuration

1. Get your Todoist API token from the Todoist Integrations settings

2. Configure the environment variable:

   # Add to your .env file or environment
   TODOIST_API_TOKEN=your_api_token_here
   

3. Configure Claude Desktop:

   // ~/.config/claude/claude_desktop_config.json or equivalent
   {
     "mcpServers": {
       "mcp-todoist": {
         "command": "uvx",
         "args": ["mcp-todoist"]
       }
     }
   }
   

Running the MCP Server

Method 1: Direct Command Line

Run the server in a terminal window:

# Set your API token
export TODOIST_API_TOKEN=your_api_token_here

# Run the server using UV
uvx mcp-todoist

Keep this terminal window open while using Claude Desktop.

Method 2: Using a Startup Script (Recommended)

1. Create a file named start-todoist-mcp.sh with the following content:

#!/bin/bash

# Set environment variables
export MCP_SERVER_NAME="mcp-todoist"
export MCP_LOG_LEVEL="INFO"
export MCP_DEBUG="true"
export TODOIST_API_TOKEN="your_todoist_api_token_here"

# Path to your Todoist MCP server
MCP_PATH="/path/to/mcp-todoist"

# Log file for debugging
LOG_FILE="${MCP_PATH}/todoist-mcp.log"

# Create log file or clear existing one
echo "Starting Todoist MCP server at $(date)" > "${LOG_FILE}"

# Navigate to the project directory
cd "${MCP_PATH}"

# Start the MCP server
echo "Starting MCP server from ${MCP_PATH}" >> "${LOG_FILE}"
uv run python -m mcp_todoist >> "${LOG_FILE}" 2>&1

2. Make the script executable:

chmod +x start-todoist-mcp.sh

3. Update your Claude Desktop configuration to use this script:

{
  "mcpServers": {
    "mcp-todoist": {
      "command": "/absolute/path/to/start-todoist-mcp.sh",
      "args": []
    }
  }
}

Using with Claude

Once configured, you can ask Claude to interact with your Todoist account with commands like:

• "Show me my tasks due today"
• "Create a new task to buy groceries tomorrow"
• "Mark my 'send email' task as complete"
• "Create a new project called 'Home Renovation'"
• "Show me all tasks in my Work project"

Available Tools

Task Management

• list-tasks - Retrieve and filter tasks
• create-task - Create a new task
• update-task - Update an existing task
• complete-task - Mark a task as completed
• delete-task - Delete a task

Project Management

• list-projects - Get all projects
• create-project - Create a new project
• update-project - Update a project
• delete-project - Delete a project

Label Management

• list-labels - Get all labels
• create-label - Create a new label
• update-label - Update a label
• delete-label - Delete a label

Utilities

• search - Search across tasks with complex filtering

Troubleshooting

If you encounter issues with the MCP server, try these debugging strategies:

Check the Logs

If using the startup script, check the log file:

cat /path/to/mcp-todoist/todoist-mcp.log

Enable Debug Mode

Set the MCP_DEBUG environment variable to true for more verbose logging:

export MCP_DEBUG=true
uvx mcp-todoist

Verify API Token

Ensure your Todoist API token is correct and still valid:

# Test the token with a simple curl request
curl -X GET \
  https://api.todoist.com/rest/v2/projects \
  -H "Authorization: Bearer $TODOIST_API_TOKEN"

Use the MCP Inspector

Debug MCP servers with the inspector tool:

npx @modelcontextprotocol/inspector uvx mcp-todoist

Common Issues and Solutions

• "MCP Server not available" error: Ensure the server is running in a separate terminal or via a startup script.
• Authentication errors: Check that your Todoist API token is correctly set in your environment.
• "Command not found" errors: Make sure Astral UV is installed and in your PATH.
• Timeout errors: If your MCP server is slow to respond, try increasing the timeout in Claude Desktop settings.

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.