Todoist MCP Integration
Setup
There are two ways to configure the Todoist MCP server. The NPX version with API token is recommended for daily use.
Option 1: NPX with API Token (Recommended)
This version uses a Todoist API token and doesn't require re-authentication. Best for regular use.
- Get your API token:
-
Go to Todoist Settings → Integrations → Developer
-
Copy your API token (or generate a new one)
- Add to ~/.claude.json at the top level:
{ "mcpServers": { "todoist": { "command": "npx", "args": ["-y", "@doist/todoist-ai"], "env": { "TODOIST_API_KEY": "your-api-token-here" } } } }
Important: The environment variable must be TODOIST_API_KEY (not TODOIST_API_TOKEN ).
- Restart Claude Code to pick up the new configuration.
Option 2: HTTP with OAuth (Alternative)
This version uses OAuth and requires periodic re-authentication (session expires after ~1 hour). Useful if you don't want to store a token.
claude mcp add --transport http todoist https://ai.todoist.net/mcp
In Claude Code, run /mcp to open the MCP panel. Click on Todoist and complete the OAuth flow.
Note: The OAuth session times out frequently. If you get connection errors, re-authenticate via /mcp .
Troubleshooting
MCP shows "failed" or won't connect:
-
Verify the env variable is TODOIST_API_KEY (not TODOIST_API_TOKEN )
-
Regenerate your API token at Todoist Developer Settings — old tokens may have expired
-
Restart Claude Code after config changes
-
Test with mcp__todoist__user-info to verify connection
Available MCP Tools
All tools are prefixed with mcp__todoist__ :
Tool Purpose
find-tasks
Search tasks by text, project, section, labels, or assignee
find-tasks-by-date
Get tasks for a date range (use startDate: "today" for today + overdue)
add-tasks
Create one or more tasks with full options
update-tasks
Modify existing tasks (move, dates, priority, descriptions, assignments)
complete-tasks
Mark tasks as done
find-projects
List or search projects
find-sections
List sections within a project
get-overview
Markdown overview of all projects or a specific project
add-projects
Create new projects
add-sections
Create sections in projects
add-comments
Add comments to tasks or projects
find-comments
Get comments on tasks or projects
search
Full-text search across tasks and projects
user-info
Get user details, timezone, goals
Task Creation Best Practices
When creating tasks from verbal descriptions:
-
Extract a clean, actionable title — don't dump raw text verbatim
-
Capture context in the description — the "why", rationale, acceptance criteria
-
Don't lose information — everything said should be captured (title or description)
-
Use imperative form — "Contact Wade" not "Contacting Wade"
MCP Task Options
content: "Task title" (required) description: "Additional details" dueString: "tomorrow at 5pm" (natural language) priority: "p1" | "p2" | "p3" | "p4" (p1 = highest) projectId: "<project-id>" or "inbox" sectionId: "<section-id>" labels: ["label1", "label2"] duration: "2h" | "90m" | "2h30m" responsibleUser: "<name>" (for shared projects)
Common Operations
List Today's Tasks
find-tasks-by-date with startDate: "today" — includes overdue items.
List Tasks in a Project
find-tasks with projectId . Use "inbox" for inbox, or get project IDs from find-projects .
Move a Task
update-tasks with projectId set to target project ID.
Assign a Task (Shared Projects)
update-tasks with responsibleUser . Note: Can't assign while task is in Inbox — move first, then assign.
Quick Overview
get-overview without parameters for all projects. Add projectId for specific project with tasks.
Migration Notes
The previous CLI tool (todoist command via Homebrew) had reliability issues — moves didn't work and sync was unreliable. The official MCP server from Doist is the recommended approach.
If you still have the CLI installed:
brew uninstall todoist