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/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