Todoist MCP Server

A Model Context Protocol (MCP) server that integrates with Todoist, allowing Claude and other MCP-compatible AI assistants to interact with your Todoist tasks and projects.

Features

• Task Management: Create, read, update, complete, and delete tasks
• Project Management: List and manage projects
• Filtering: Filter tasks by project, section, labels, or natural language queries
• Full API Support: Comprehensive coverage of Todoist's REST API v2

Installation

Prerequisites

• Python 3.12 or higher
• pip (Python package installer)
• A Todoist account and API token

Step 1: Get Your Todoist API Token

1. Go to Todoist Integrations Settings
2. Scroll down to the "API token" section
3. Copy your API token (you'll need this later)

Step 2: Install the MCP Server

1. Clone the repository:

git clone <repository-url>
cd todoist-mcp

2. Install the package:

pip install -e .

Note: If you want to install it in a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

3. Create a .env file with your API token:

# Create .env file in the todoist-mcp directory
echo "TODOIST_API_TOKEN=your_api_token_here" > .env

Replace your_api_token_here with the token you copied in Step 1.

Step 3: Configure Claude Desktop

The Claude Desktop configuration file is located at:

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

Option A: Using Virtual Environment (Recommended for Development)

If you installed in a virtual environment, use the full path to the todoist-mcp command:

{
  "mcpServers": {
    "todoist": {
      "command": "/full/path/to/venv/bin/todoist-mcp"
    }
  }
}

To find the full path, run:

which todoist-mcp  # On macOS/Linux
where todoist-mcp  # On Windows

Option B: Global Installation

If you installed globally (without a virtual environment), you can use:

{
  "mcpServers": {
    "todoist": {
      "command": "todoist-mcp"
    }
  }
}

Important Notes:

• The MCP server will automatically load the TODOIST_API_TOKEN from the .env file in the todoist-mcp directory
• You do NOT need to specify the token in the Claude Desktop config if you're using a .env file
• After updating the config, fully restart Claude Desktop (quit the app completely, don't just close the window)

Step 4: Verify Installation

1. Restart Claude Desktop completely (use Quit from the menu)
2. Open Claude Desktop
3. Look for the MCP server indicator (usually in the bottom corner or settings)
4. You should see "todoist" listed as an available MCP server
5. Try asking Claude: "Show me my Todoist tasks"

Troubleshooting

"Could not connect to MCP server" or "spawn todoist-mcp ENOENT"

• Make sure you used the full path to todoist-mcp if using a virtual environment
• Verify the command exists by running which todoist-mcp (macOS/Linux) or where todoist-mcp (Windows)
• Check that your .env file exists in the todoist-mcp directory with the correct token

"TODOIST_API_TOKEN environment variable not set"

• Ensure your .env file is in the todoist-mcp directory (same directory as pyproject.toml)
• Verify the .env file contains: TODOIST_API_TOKEN=your_actual_token
• Check for typos in the variable name

Server keeps disconnecting

• Verify your API token is valid at https://todoist.com/app/settings/integrations/developer
• Check that you've fully restarted Claude Desktop
• Look at Claude Desktop logs for specific error messages

Usage

With Claude Desktop

Once configured, you can interact with Claude using natural language:

• "Show me all my tasks for today"
• "Create a task to review the quarterly report due tomorrow"
• "Mark task ID 12345 as completed"
• "List all my projects"
• "Create a new project called 'Home Renovation'"
• "Show me all high-priority tasks"

As a Standalone Server (Advanced)

You can also run the MCP server directly for testing or integration with other MCP clients:

# Make sure your .env file is configured first
todoist-mcp

Available Tools

Task Operations

• get_tasks - List tasks with optional filtering
• get_task - Get details of a specific task
• create_task - Create a new task
• update_task - Update an existing task
• complete_task - Mark a task as completed
• reopen_task - Reopen a completed task
• delete_task - Delete a task

Project Operations

• get_projects - List all projects
• get_project - Get details of a specific project
• create_project - Create a new project

Section Operations

• get_sections - List sections within projects

Example Interactions

Once connected, you can interact with Claude using natural language:

• "Show me all my tasks for today"
• "Create a task to review the quarterly report due tomorrow"
• "Mark task ID 12345 as completed"
• "List all my projects"
• "Create a new project called 'Home Renovation'"

Development

Project Structure

todoist-mcp/
├── todoist_mcp/
│   ├── __init__.py
│   ├── client.py      # Todoist API client
│   └── server.py      # MCP server implementation
├── pyproject.toml
├── README.md
└── .env.example

Running Tests

(Tests would be added here in the future)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the terms specified in the LICENSE file.