todoist-mcp-server by gekitsuu - MCP Server

Todoist MCP Server

A Model Context Protocol (MCP) server that integrates Todoist task management with Claude. Manage your Todoist tasks conversationally without context-switching!

Features

Get Tasks: Fetch and filter tasks by project, label, or custom filters
Create Tasks: Add new tasks with priorities, due dates, and labels
Update Tasks: Modify existing tasks, change priorities, defer dates
Complete Tasks: Mark tasks as done
List Projects: View all your Todoist projects
List Labels: View all your Todoist labels

Perfect for:

Managing tasks during high-stress work periods
Bulk task operations (defer, prioritize, organize)
Quick task triage without leaving your conversation with Claude
ADHD-friendly task management with conversational interface

Prerequisites

Python 3.10 or higher
A Todoist account
Todoist API token (get it here)

Installation

1. Clone the repository

git clone https://github.com/yourusername/todoist-mcp-server.git
cd todoist-mcp-server

2. Create a virtual environment (recommended)

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install the package

pip install -e .

4. Configure your API token

Create a .env file in the project root:

cp .env.example .env

Edit .env and add your Todoist API token:

TODOIST_API_TOKEN=your_actual_token_here

Get your token from: https://todoist.com/app/settings/integrations/developer

Configuration for Claude Code

Option 1: Configure in Claude Desktop (Recommended)

Add this to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "todoist": {
      "command": "python",
      "args": ["-m", "todoist_mcp.server"],
      "env": {
        "TODOIST_API_TOKEN": "your_token_here"
      }
    }
  }
}

Option 2: Use with Claude Code CLI

If using with claude-code CLI:

# Set environment variable
export TODOIST_API_TOKEN=your_token_here

# Run the server
python -m todoist_mcp.server

Or configure in your MCP settings file for Claude Code.

Restart Claude

After configuration, restart Claude Desktop or Claude Code to load the MCP server.

Usage Examples

Once configured, you can interact with Todoist through natural conversation with Claude:

View Today's Tasks

You: "Show me my tasks for today"

Claude will use todoist_get_tasks with filter="today"

Create a Task

You: "Create a task to review the infrastructure PR, priority 4, due tomorrow"

Claude will use todoist_create_task with appropriate parameters

Bulk Defer Tasks

You: "I'm overwhelmed. Show me all my tasks for today, then defer everything
      except priority 4 items to next week"

Claude will:
1. Use todoist_get_tasks to see today's tasks
2. Use todoist_update_task to defer non-urgent items

Organize by Project

You: "Show me my projects, then move all high-priority tasks to the 'Sprint' project"

Claude will:
1. Use todoist_get_projects to list projects
2. Use todoist_update_task to move tasks

Complete Tasks

You: "I just finished the deployment. Mark that task as complete"

Claude will use todoist_complete_task

Available Tools

todoist_get_tasks

Fetch tasks with optional filters.

Parameters:

project_id (optional): Filter by project ID
label (optional): Filter by label name
filter (optional): Todoist filter query (e.g., "today", "overdue", "priority 1")

todoist_create_task

Create a new task.

Parameters:

content (required): Task title/content
description (optional): Task description
project_id (optional): Project to add task to
priority (optional): 1-4 (4 is highest)
due_string (optional): Human-readable due date ("tomorrow", "next Monday", etc.)
labels (optional): Array of label names

todoist_update_task

Update an existing task.

Parameters:

task_id (required): ID of task to update
content (optional): New task content
description (optional): New description
priority (optional): New priority (1-4)
due_string (optional): New due date
labels (optional): New labels array (replaces existing)

todoist_complete_task

Mark a task as complete.

Parameters:

task_id (required): ID of task to complete

todoist_get_projects

List all projects (no parameters required).

todoist_get_labels

List all labels (no parameters required).

Troubleshooting

"TODOIST_API_TOKEN not set" error

Make sure you've created a .env file with your token
Or set the environment variable in your shell/Claude config
Get your token from: https://todoist.com/app/settings/integrations/developer

Server not appearing in Claude

Check that your claude_desktop_config.json syntax is correct
Restart Claude Desktop completely
Check Claude's logs for MCP connection errors

API errors

Verify your token is valid and hasn't expired
Check your internet connection
Some operations require Todoist Premium (like labels)

Development

Running tests

pip install -e ".[dev]"
pytest

Code formatting

black src/
ruff check src/

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

MIT License - see file for details.

Acknowledgments

Built with the Model Context Protocol
Uses the Todoist API
Created for better ADHD-friendly task management

Support

For issues and feature requests, please open an issue.

Testing

The project includes a comprehensive test suite to ensure reliability.

Running Tests

# Install test dependencies
pip install pytest pytest-asyncio

# Run all tests
PYTHONPATH=src pytest tests/ -v

Test Coverage

The test suite includes:

API Method Validation: Ensures we're calling valid Todoist API methods (would have caught the close_task vs complete_task bug)
Handler Function Tests: Unit tests for all MCP handlers with mocked API calls
Error Handling Tests: Validates proper error handling and user-friendly messages

See for more details.

gekitsuu/todoist-mcp-server