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.
1. Get your API token:
- Go to Todoist Settings → Integrations → Developer
- Copy your API token (or generate a new one)
2. 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).
3. 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/mcpIn 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(notTODOIST_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-infoto 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