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.
Tools 14
get_taskFetch a single task by IDfind_tasksFilter tasks by Todoist query string, project, or labelfind_tasks_by_dateTasks due on or between datesget_projectsList all projectsget_sectionsList sections in a projectget_commentsGet comments on a taskget_overviewOverdue + today summary, or all tasks in a projectadd_taskCreate a task (supports due_string, priority, labels)update_taskUpdate content, description, priority, or labelscomplete_taskMark a task doneadd_projectCreate a projectadd_sectionCreate a sectionadd_commentAdd a comment to a taskreschedule_taskMove a task to a new date, safely preserving recurring patterns and remindersEnvironment Variables
TODOIST_API_TOKENrequiredTodoist API token from Settings -> Integrations