Todoist MCP: Complete Guide (2026)

TL;DR + what you actually need

The Todoist MCP server is a stdio process — a local subprocess your MCP client launches — that exposes the Todoist API as tools Claude can call, so an agent can read, create, and manage your tasks in plain language. Three things get you running:

• One secret: TODOIST_API_TOKEN — a single token from Settings → Integrations → Developer in Todoist. No OAuth, no client ID, no callback URL. That one string is your whole account.
• One package: @greirson/mcp-todoist — the most-installed community server, MIT-licensed, TypeScript, 19 consolidated tools, run via npx. It is the implementation our /servers/todoist entry tracks.
• One safety switch: DRYRUN=true — simulates every mutation against your real data without changing anything. Turn it on the first time you point an agent at a bulk operation.

The copy-paste, if that’s all you came for:

claude mcp add todoist \
  -e TODOIST_API_TOKEN="your_api_token" \
  -- npx @greirson/mcp-todoist

Also worth knowing before you scroll: Todoist’s maker, Doist, ships an official MCP server too. If you value first-party maintenance over raw tool count, you may want that one instead — the official-vs-community section below lays out the trade cleanly.

What Todoist MCP actually does

You ask “capture everything I need to do for the launch as tasks in my Work project, due next Friday”, and the agent calls todoist_task (or the bulk variant) with the titles, project, and a natural-language due date. You ask “what’s overdue and what can I drop?” and it queries your tasks, reasons over them, and hands you a plan. Every step is a real API call against your account, not a guess about what your list contains.

The implementation this guide centers on lives at github.com/greirson/mcp-todoist — TypeScript, MIT-licensed, and actively maintained, with a modular tool layer and a proper test suite behind it. It does no AI work itself: agent calls come in, Todoist REST and Sync API calls go out, and the token is the only state it holds. That thin-wrapper shape is exactly what you want — the intelligence is your model’s, the source of truth is Todoist.

Why this matters beyond novelty: a task manager is where intent goes to get organized, and an LLM is good at turning messy intent into structured items. Todoist has leaned into that — the company’s founder has publicly welcomed the agentic tooling growing around the product:

Amir Salihefendić is the founder and CEO of Doist, the company behind Todoist; his post quoted a developer using Todoist as the task tracker for cross-repo Claude Code work. That is the shape of it: the model does the doing, Todoist holds the list, MCP is the wire between them.

Auth: one API token, and it is your whole account

Todoist’s auth for this is refreshingly plain. There is no OAuth dance for the personal-token path: you grab one token and set it as an env var. In Todoist, open Settings → Integrations → Developer (direct link: todoist.com/app/settings/integrations/developer), copy the API token, and hand it to the server as TODOIST_API_TOKEN.

The simplicity has a sharp edge worth stating plainly: that token is full read-write access to your entire Todoist. There are no scopes to narrow it, no read-only variant. Anything you can do in the app — complete a task, delete a project, edit every due date — a process holding that token can do too. So keep it out of any file you commit (every MCP client supports an env block for exactly this reason), and if it ever leaks, reset it from the same Developer page, which immediately invalidates the old value everywhere.

One consequence: because the token is account-wide and unscoped, this is a personal-productivity integration, not a shared-service one. An agent acting on a whole team’s workspace with per-user permissions is a different architecture than one personal token in one env var.

Official Doist server vs the community server

There are several Todoist MCP servers in the wild, but the real choice is between two: Doist’s own and the community greirson build. Both are MIT-licensed and both authenticate with the same kind of Todoist token, so the decision is about maintenance model and tool surface, not licensing.

Our read: start with the official server if your priority is “this keeps working when Todoist changes its API,” or if you want to import the tools into your own agent. Reach for the community greirson server when you want the wide surface — bulk operations, subtask hierarchies, label analytics, the dry-run safety net — and accept that a community project moves at its own pace. This guide covers the greirson server in depth because it is the one our catalog tracks; the install steps below map cleanly to either.

Install (every client)

The community server is stdio-only — your MCP client launches npx @greirson/mcp-todoist as a subprocess with the token in its env. There are two distribution paths worth knowing:

• Claude Desktop one-click: download the todoist-mcp.mcpb bundle from the latest release, double-click it (or drag it onto Claude Desktop), and paste your token when prompted. No JSON editing at all — the fastest install of any server in this guide series.
• npx everywhere else: the same binary registered manually in any MCP client’s config, with TODOIST_API_TOKEN in the env block.

The install panel below pulls its config from the canonical /servers/todoist catalog entry, so it stays in sync with the package name and env-var shape. Pick your client, copy, paste, drop in your token, restart.

One-line install · Todoist

Open server page

Install

Cursor

One-click install

VS Code

One-click install

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

Client-specific notes:

• Claude Code — one line: claude mcp add todoist -e TODOIST_API_TOKEN=your_token -- npx @greirson/mcp-todoist. Add --scope project to register it in the repo’s .mcp.json instead of your user config — but keep the token out of the committed file. Full flag reference at /clients/claude-code.
• Claude Desktop (manual) — if you skip the .mcpb bundle, paste the JSON block from the install card into claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/), then restart the app.
• Cursor — same JSON shape in ~/.cursor/mcp.json. See /clients/cursor.
• VS Code / Windsurf — the JSON snippet from the install card goes in the client’s MCP config file (~/.codeium/windsurf/mcp_config.json for Windsurf).

Codex CLI

Codex reads MCP servers from ~/.codex/config.toml:

[mcp_servers.todoist]
command = "npx"
args = ["@greirson/mcp-todoist"]

[mcp_servers.todoist.env]
TODOIST_API_TOKEN = "your_api_token"

Restart Codex and confirm with codex mcp list. Prefer not to keep the token in TOML? Omit the env table and export TODOIST_API_TOKEN in the shell that launches Codex. Browse every supported client and its config path at mcp.directory/clients.

Tools walkthrough

The server ships 19 tools, consolidated so related operations share one tool with an action parameter (e.g. todoist_task handles create, get, update, delete, complete, reopen, and quick_add). That consolidation is deliberate — fewer, richer tools keep the model’s tool list short and its choices clearer. Grouped by what agents actually do with them:

Tasks — the core

todoist_task covers the full task lifecycle including quick_add, which parses Todoist natural-language syntax (#Project, @label, +assignee, p1–p4 priority, {deadline}, and //description) exactly like the app. todoist_task_bulk does the same operations across many tasks at once, and todoist_task_ops adds move, reorder, and close. Addressing a task by its ID is more reliable than by name — the README says so outright, and it avoids the fuzzy-search misfires discussed below.

Subtasks & hierarchy

todoist_subtask creates children, converts a task into a subtask, promotes one back up, and returns a completion-tracked hierarchy for a parent. This is the group that makes “break the launch into subtasks” a single prompt.

Projects, sections, labels

todoist_project and todoist_project_ops handle project CRUD, sharing, reordering, and archived retrieval; todoist_section manages the columns inside a project; todoist_label does label CRUD plus usage statistics — a genuinely nice touch for “which labels do I actually use?” cleanups.

Comments, reminders, filters

todoist_comment reads and writes task and project comments. todoist_reminder and todoist_filter cover Todoist Pro features — relative and absolute reminders, and saved custom filters — so those calls need a Pro account.

Accounts, activity, and utilities

todoist_user returns profile info, productivity stats, and karma history; todoist_activity reads the account’s audit trail; todoist_completed retrieves done tasks and their stats; todoist_backup lists and downloads Todoist’s automatic backups. Rounding it out: todoist_collaboration, todoist_notes, workspace todoist_shared_labels (Business), and todoist_utility, whose test_connection action is the first thing to run when something looks off.

Dry-run mode: the feature that earns trust

Most connectors hand an agent live write access and hope for the best. This server ships a real safety valve. Set DRYRUN=true in the env block and every mutating operation — create, update, complete, delete, in single and bulk form — is simulated: validated against your real account data, logged with a clear [DRY-RUN] prefix, but never actually executed. Read operations still hit the live API, so the simulation is grounded in your actual projects and tasks.

{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["@greirson/mcp-todoist"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token",
        "DRYRUN": "true"
      }
    }
  }
}

Why it matters: the scariest prompt you can give a task-manager agent is a bulk one — “complete every task containing ‘review’ and delete anything overdue by a month”. Run that dry first, read the [DRY-RUN] lines to see which tasks it matched, then flip the switch off and run it for real. That turns “trust the model” into “verify, then trust” — the right default when the blast radius is your entire to-do list. Remove the variable (or set it to false) and restart when you’re done.

Recipes

Five workflows where the install pays for itself. All assume the server is registered and the token is valid.

Recipe 1 — Turn a conversation into tasks

“From these meeting notes, create tasks in my Work project for every action item assigned to me, due the day before each deadline mentioned.” The agent parses the notes, calls todoist_task_bulk with titles, project, and natural-language due dates, and reports back the list it created. This is the flagship use case — capture without context-switching out of the conversation.

Recipe 2 — Morning triage

“Show me everything overdue and everything due today. Group by project, flag anything I’ve rescheduled more than twice, and suggest what to drop.” Read-only, so it’s safe to run unattended and a good first test of a fresh install. The value isn’t the data — it’s the model’s judgment over it.

Recipe 3 — Break a goal into subtasks

“Take the task ‘Ship v2 landing page’ and break it into subtasks: copy, design, build, QA, launch — each with a sensible due date this month.” todoist_subtask builds the hierarchy under the parent in one pass, and hierarchy reads it back with completion tracking so you can watch progress.

Recipe 4 — Bulk reschedule after a slip

“I lost this week. Push every incomplete task due before Friday to next week, keeping the relative order.” todoist_task_bulk with an update action. This is the recipe to run with DRYRUN=true the first time — confirm the matched set before you move real deadlines.

Recipe 5 — Label and project hygiene

“Show label usage stats, tell me which labels I haven’t used in months, and list projects with no active tasks so I can archive them.” todoist_label stats plus project reads turn a nagging maintenance chore into a two-minute review. One r/todoist user captured the appeal: it “helps me get out from under a pile of overwhelming tasks.”

Gotchas we hit (and what the issue tracker taught us)

A task-manager connector is unusually easy to trust and unusually easy to get subtly wrong, because a call can return a success-shaped response while doing nothing you intended. Here is what actually bites people, each traced to its root cause in the project’s issue tracker.

• Due dates: use words, not the date field. We assumed due_date (YYYY-MM-DD) was the reliable way to set a deadline. It isn’t — as of this writing that parameter is silently dropped on create and update, and only due_string (natural language like “tomorrow” or “Jan 23”) actually reaches Todoist (issue #94). Phrase due dates in words and verify in the app after the first write.
• Priority numbers are inverted from the app labels. Todoist’s REST API integer priority runs opposite to the P1–P4 labels you see in the app (API-side, the highest integer is the most urgent; the app shows the reverse). That mismatch produced a real priority-inversion bug (issue #28, since fixed). The safe habit: set priority through Quick Add’s p1–p4 syntax, which follows the app, or say “high priority” and let the model map it — then glance at the result.
• Old versions break in Claude Code. Early releases advertised tool schemas with oneOf/anyOf at the top level, which Claude Code v2.0.50+ rejects with a 400 invalid_request_error (issue #48). The maintainer flattened the schemas; running @greirson/mcp-todoist via npx (which pulls latest) fixes it. If you see that error, you’re on a stale cached version.
• Task search does fuzzy things; IDs don’t. Several closed issues describe name-based task lookup matching the wrong task or missing one. The README recommends addressing tasks by ID for exactly this reason. In practice: let the agent list tasks, grab the ID, then act on the ID — especially for deletes.
• Moves and closes needed an API migration. Move/close operations once failed with 410 Gone because they hit Todoist’s deprecated Sync API v8 (issue #74). It was migrated to v1. Again, the fix is: run the latest, keep nothing pinned.

The pattern across all five: this is a fast-moving community project wrapping an API that itself changes. That’s the honest trade for its wide tool surface — and the reason the “run @latest, verify with dry-run” habit pays off.

Limits & safety

• The token is unscoped. One TODOIST_API_TOKEN equals full account access — no read-only mode, no per-project scope. Your blast radius is everything. Dry-run and your client’s tool-approval prompt are the guardrails; use both for anything destructive.
• Some tools need a paid Todoist plan. Reminders and custom filters are Pro features; shared/workspace labels are Business. Those calls fail on a free account — that’s Todoist’s gating, not the server’s. Task, project, section, label, and comment tools all work on free Todoist.
• Comments can mangle markdown. As of this writing, comment content is HTML-entity-encoded before it’s sent, so backticks, quotes, and angle brackets render as escaped entities in Todoist (issue #82). Fine for plain-text comments; watch out if you expect formatted ones.
• Todoist API rate limits apply. The API meters requests, and a loop hammering reads across hundreds of tasks can hit the ceiling. One r/todoist user noted that at a normal “dozen things” cadence you never see a limit; batch-heavy automations are where you would. Tell the agent to batch, not iterate.
• Context cost scales with your list. Reading a huge project dumps a lot of tasks into the model’s context window. Scope prompts to a project, a filter, or a date window rather than “read everything.”

Cost of the server itself: zero. MIT-licensed, free Todoist token, no hosted tier to pay for. It’s a strong entry on our best free MCP servers list for that reason — the only thing it consumes is your own API rate-limit headroom.

Troubleshooting

The verdict

The community sentiment tracks this. On r/todoist, a reliable Todoist-plus-Claude integration drew a telling line — relief at one that “doesn’t break every other day.” Stability, not features, decides whether a productivity integration sticks. Match the server to how much you value that: official for steadiness, community for reach.

FAQ

Sources

• Primary — community implementation, README, and issue tracker: github.com/greirson/mcp-todoist (MIT, TypeScript, @greirson/mcp-todoist on npm)
• Primary — official Doist server: github.com/Doist/todoist-mcp (MIT, @doist/todoist-mcp)
• Primary — Todoist API token page: todoist.com/app/settings/integrations/developer
• Community — Doist founder on Todoist in agentic workflows: @amix3k, July 1 2026
• Community — r/todoist reactions: “An official MCP for Todoist with Claude!” · “Anyone using AI/Claude with Todoist MCP?”
• Community — behavior bugs referenced above: due_date #94, priority inversion #28, Claude Code schema #48, Sync API v8 #74
• Canonical MCP.Directory entry: /servers/todoist
• Related guides: n8n MCP · Jira MCP · Awesome MCP Servers (2026)