How do I use todoist-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@todoist-mcp Add a task to buy milk tomorrow at 9 AM with high priority" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

todoist-mcp

A Python MCP server for Todoist that provides safe task rescheduling.

The official Todoist MCP server's task-update tool silently drops reminders and flattens recurring tasks when changing due dates. This server fixes that by routing all date changes through a custom reschedule_task tool that preserves both.

Tools

Read

Tool	Description
`get_task`	Fetch a single task by ID
`find_tasks`	Filter tasks by Todoist query string, project, or label
`find_tasks_by_date`	Tasks due on or between dates
`get_projects`	List all projects
`get_sections`	List sections in a project
`get_comments`	Get comments on a task
`get_overview`	Overdue + today summary, or all tasks in a project

Write

Tool	Description
`add_task`	Create a task (supports due_string, priority, labels)
`update_task`	Update content, description, priority, or labels — no due-date params
`complete_task`	Mark a task done
`add_project`	Create a project
`add_section`	Create a section
`add_comment`	Add a comment to a task

Rescheduling

Tool	Description
`reschedule_task`	Move a task to a new date, safely preserving recurring patterns and reminders

update_task deliberately has no due-date parameters in its schema. The model cannot use it to change dates even if instructed to — reschedule_task is the only path.

Setup

Prerequisites

uv
A Todoist API token (find it at Todoist → Settings → Integrations → API token)

Install

git clone https://github.com/kpanko/todoist-mcp
cd todoist-mcp
cp .env.example .env
# edit .env and add your token
uv sync

Configure Claude Code

Add to your MCP config (.claude/mcp_config.json or Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "todoist": {
      "command": "uv",
      "args": [
        "--project", "/path/to/todoist-mcp",
        "run", "todoist-mcp"
      ]
    }
  }
}

The server reads TODOIST_API_TOKEN from the environment or from a .env file in the project root. No OAuth or browser auth required — works in headless background services.

Dependencies

todoist-api-python — official REST client
fastmcp — MCP server framework
todoistScheduler — local dependency providing the reschedule logic (reminders via Sync API, recurrence string preservation)

Why not use the official server?

The official server at https://ai.todoist.net/mcp requires OAuth (browser flow), making it unsuitable for background services. It also exposes an update_task tool that accepts due-date parameters, which the Todoist REST API handles by dropping reminders and converting recurring tasks to one-time tasks.