Skip to main content
Glama

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

Related MCP server: Todoist MCP Server

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

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

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.

Available Tools

11 tools
complete_taskB

Mark a task as completed.

Args:
    task_id: The ID of the task to complete

Inputs: task_id (required). Returns: result

create_projectB

Create a new project in Todoist.

Args:
    name: The name of the project
    parent_id: Parent project ID (for nested projects)
    color: Project color
    is_favorite: Whether to mark as favorite

Inputs: name (required), parent_id, color, is_favorite. Returns: result

create_taskA

Create a new task in Todoist.

Args:
    content: The task content/title
    description: Detailed description of the task
    project_id: Project ID to add the task to
    section_id: Section ID within the project
    parent_id: Parent task ID (for subtasks)
    labels: List of label names
    priority: Priority from 1 (normal) to 4 (urgent)
    due_string: Human readable due date (e.g., 'tomorrow', 'next Monday')
    due_date: ISO 8601 formatted due date

Inputs: content (required), description, project_id, section_id, +5 more. Returns: result

delete_taskC

Delete a task.

Args:
    task_id: The ID of the task to delete

Inputs: task_id (required). Returns: result

get_projectA

Get a specific project by ID.

Args:
    project_id: The ID of the project to retrieve

Inputs: project_id (required). Returns: result

get_projectsB

Get all projects from Todoist.

Inputs: no named parameters. Returns: result

get_sectionsC

Get sections from a project.

Args:
    project_id: Project ID to get sections from (optional)

Inputs: project_id. Returns: result

get_taskC

Get a specific task by ID.

Args:
    task_id: The ID of the task to retrieve

Inputs: task_id (required). Returns: result

get_tasksC

Get tasks from Todoist with optional filtering.

Args:
    project_id: Filter tasks by project ID
    section_id: Filter tasks by section ID
    label: Filter tasks by label
    filter_query: Natural language filter (e.g., 'today', 'overdue', 'p1')

Inputs: project_id, section_id, label, filter_query. Returns: result

reopen_taskC

Reopen a completed task.

Args:
    task_id: The ID of the task to reopen

Inputs: task_id (required). Returns: result

update_taskB

Update an existing task.

Args:
    task_id: The ID of the task to update
    content: Updated task content/title
    description: Updated task description
    labels: Updated list of label names
    priority: Updated priority from 1 (normal) to 4 (urgent)
    due_string: Updated human readable due date
    due_date: Updated ISO 8601 formatted due date

Inputs: task_id (required), content, description, labels, +3 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 11 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose with no ambiguity. The tools are organized around specific resources (tasks, projects, sections) and actions (create, get, update, delete, complete, reopen), making it easy for an agent to select the right tool. For example, 'complete_task' and 'reopen_task' handle task state changes, while 'update_task' handles content modifications.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern throughout, using snake_case. The verbs are clear and appropriate (e.g., create, get, update, delete, complete, reopen), and nouns specify the resource (e.g., task, project, sections). There are no deviations or mixed conventions.

    Tool Count5/5

    With 11 tools, this server is well-scoped for managing Todoist tasks and projects. Each tool earns its place by covering essential operations like CRUD for tasks and projects, plus specific actions like completing/reopening tasks and retrieving sections. The count is neither too thin nor excessive for the domain.

    Completeness5/5

    The tool surface provides complete CRUD/lifecycle coverage for tasks and projects, with no obvious gaps. It includes creation, retrieval, updating, and deletion for both resources, plus state management (complete/reopen) for tasks and section retrieval. This allows agents to handle all core workflows without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers