Todoist MCP Server

How to use

Start the MCP server using one of the provided runtime configurations, then connect your MCP client (such as Claude) with the corresponding server profile. You can create tasks, fetch tasks with filters, update task attributes, delete tasks, and mark tasks as complete through clearly named tools. Make sure you supply your Todoist API token via the configured environment variable to enable API access.

How to install

Prerequisites you need before starting the server are Python 3.12 and the UV tooling used to run MCP servers. You also need a Todoist account and a Todoist API token.

Choose one of the following installation/run paths.

Option A — Run via UVX without cloning
Follow these commands to run directly from the source repository using UVX.

uvx --from https://github.com/Johnxjp/todoist-mcp-python.git mcp-server-todoist

Additional configurations and setup

Configure the MCP connection in your client to point to one of the server configurations shown below. You will provide your Todoist API token in the environment variables for secure access.

Option A configuration (UVX-based run) shows how to reference the remote source and pass the token through an environment variable.

{
  "mcpServers": {
    "todoist-server": {
      "command": "uvx",
      "args": [
        "--from", 
        "https://github.com/Johnxjp/todoist-mcp-python.git", 
        "mcp-server-todoist"
      ],
      "env": {
        "TODOIST_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Additional configurations and setup

Option B configuration (cloned repository) shows how to run from a local copy using uv and the Python MCP runtime.

git clone [email protected]:Johnxjp/todoist-mcp-python.git
```

```
{
  "mcpServers": {
    "todoist-server": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with",
        "todoist_api_python",
        "mcp",
        "run",
        "/full/path/to/todoist_server.py"
      ],
      "env": {
        "TODOIST_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Available tools and how to use them

The server exposes the following task-management tools you can invoke through your MCP client.

Tools

• create_task: Create a new Todoist task with a required content field and optional description, due date, priority, project, section, and labels.
• get_tasks: Retrieve a list of Todoist tasks with optional filters like project_id, project_name, task_name, priority, labels, is_overdue, and limit.
• update_task: Update an existing task identified by task_id with optional changes to content, description, labels, priority, due_date (YYYY-MM-DD), and deadline_date (YYYY-MM-DD).
• delete_task: Delete a task by task_id
• complete_task: Mark a task as complete by task_id

Security considerations

Your Todoist API token is handled securely via environment variables. Do not share your environment file or expose this token publicly. The MCP server runs locally and communicates only with the Todoist API.

Notes and examples

Practical example interactions you can perform with Claude through the Todoist MCP Server include creating tasks, listing urgent tasks, querying due dates, updating priorities, and marking tasks as complete.

create_task

Create a new Todoist task with a required content field and optional description, due date, priority, project, section, and labels.

get_tasks

Retrieve a list of Todoist tasks with optional filters like project_id, project_name, task_name, priority, labels, is_overdue, and limit.

update_task

Update an existing task identified by task_id with optional changes to content, description, labels, priority, due_date (YYYY-MM-DD), and deadline_date (YYYY-MM-DD).

delete_task

Delete a task by task_id

complete_task

Mark a task as complete by task_id