MCP Todoist

A Model Context Protocol (MCP) server that enables Claude to interact with your Todoist account.

Features

Manage tasks: create, update, complete, and delete tasks
Organize tasks in projects and with labels
Search and filter tasks based on various criteria
Seamless integration with Claude Desktop

Prerequisites

Python 3.11+
Astral UV
Todoist account and API token
Claude Desktop (for using the MCP server)

Quick Start

1. Installation

# Install using UV
uvx mcp-todoist

2. Configuration

Get your Todoist API token from Todoist Integrations settings

Configure the environment variable:

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

Configure Claude Desktop:

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

3. Using with Claude

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

"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

Running the MCP Server

There are multiple ways to run the Todoist 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

# Alternative: Run from source
cd /path/to/mcp-todoist
uv run python -m mcp_todoist

Keep this terminal window open while using Claude Desktop.

Method 2: Using a Startup Script (Recommended)

Create a startup script that Claude Desktop can use to automatically start the server:

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

Make the script executable:

chmod +x start-todoist-mcp.sh

Update your Claude Desktop configuration to use this script:

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

This approach offers several advantages:

The server starts automatically with Claude Desktop
All logs are captured in a file for easier debugging
Environment variables are set consistently

Debugging

If you encounter issues with the MCP server, here are some debugging strategies:

1. Check the Logs

If using the startup script, check the log file:

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

2. Enable Debug Mode

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

export MCP_DEBUG=true
uvx mcp-todoist

3. 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"

4. Use the MCP Inspector

The MCP Inspector is a powerful tool for debugging MCP servers:

npx @modelcontextprotocol/inspector uvx mcp-todoist

This will open a web interface showing all communications between Claude and the MCP server.

5. 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.

Development

Setup

# Clone the repository
git clone https://github.com/yourusername/mcp-todoist.git
cd mcp-todoist

# Install dependencies
uv sync

Testing

# Run tests
uv run pytest

Local Development

For local development, you can create a .env file with your Todoist API token:

TODOIST_API_TOKEN=your_api_token_here

Then run the server:

uv run python -m mcp_todoist

License

MIT License - see LICENSE file for details.