Todoist MCP vs CLI for AI Assistants

Todoist is unusual in that both routes are official. Doist, the company behind it, runs a hosted MCP server at https://ai.todoist.net/mcp and publishes a command-line tool, td. Use the MCP server for chat assistants such as Claude, ChatGPT or Cursor: it signs in through the browser and asks for read and write access to your tasks. Use the CLI for coding agents that already run shell commands, especially when you want them read-only, because td auth login --read-only gives the agent a token that cannot change anything. Use the Todoist API directly, with a personal token or an OAuth app, for scripts that run on a schedule. All three end up at the same API with your account.

Connecting the MCP server to Claude and Claude Code, step by step, is in Todoist MCP with Claude. This post is about choosing between the routes, not setting one up. The same question for other tools is answered in Trello MCP or CLI and Linear MCP vs CLI vs API.

The routes at a glance

• Hosted MCP server: one address for every client. The assistant sees a set of Todoist tools and picks one mid-conversation. Sign-in is OAuth.
• The td CLI: an npm package, @doist/todoist-cli, that the agent runs as shell commands such as td today or td add. It signs in with OAuth too, and can be read-only.
• The Todoist API v1: https://api.todoist.com/api/v1/, called by your own code with a personal token or an OAuth app’s token.
• A fourth, for builders: the MCP server’s tools published as a library, @doist/todoist-mcp, that you import into your own AI application.

Route 1: the hosted MCP server

Any client that supports remote MCP servers can connect to the address above. Todoist’s help centre↗ (opens in a new tab) says the connection asks for the data:read_write scope, which lets the assistant read and change your Todoist data, and that you can review or revoke the token at any time under Settings, then Integrations. Disconnecting from the assistant’s side revokes the token too.

The server’s tools are written for conversations: finding tasks by date, adding several tasks in one call, completing, rescheduling, and working with projects, sections, labels and comments. What it does not offer is a read-only connection. If you want a chat assistant that can only look, the control sits in the client, for example Claude’s per-tool “Needs approval” and “Blocked” settings, which the Claude guide above covers.

Choose this route when the assistant has no shell, when you want nothing to install, or when several people each connect their own account. It is also the only route that works the same in a browser chat, a desktop app and an editor.

Route 2: the td command-line tool

The CLI is Doist’s own, installed with npm install -g @doist/todoist-cli. According to its README↗ (opens in a new tab), td auth login opens the browser for an OAuth sign-in and stores the token in your operating system’s credential manager, and refuses to fall back to a plain file unless you ask for it with --credential-store=plaintext. The detail that matters most for agents is --read-only: it requests a token with the data:read scope, and the CLI blocks every command that would create, update, complete, move or delete.

npm install -g @doist/todoist-cli
td auth login --read-only     # browser sign-in, token with data:read only
td auth status                # shows read-only, read-write or unknown
td skill install claude-code  # teaches Claude Code the td commands
td today --json               # what the agent will actually run

The skill command writes an instruction file into the agent’s own skills folder, and the README lists versions for Codex, Copilot, Cursor, Gemini and a universal format. That is how the agent learns the commands without you pasting help text into every session. For machine-readable output, list commands take --json, --ndjson or --ids-only.

Two cautions. A token you paste with td auth token, or set in the TODOIST_API_TOKEN environment variable, takes priority over the stored sign-in and is treated as write-capable, because the CLI cannot tell its scope. So an agent working in a shell where that variable is set is not read-only, whatever you logged in with. And the CLI, like any shell route, needs an agent that can run commands with your approval; a chat app cannot use it.

Route 3: the Todoist API with a token

Underneath both is the API. Todoist’s API reference↗ (opens in a new tab) describes v1 as a new API that unifies the old Sync API v9 and REST API v2, so older tutorials may use endpoints that have moved. You authorise with a Bearer token: your personal API token from the integrations settings for your own scripts, or an OAuth token for anything other people install.

curl https://api.todoist.com/api/v1/tasks \
  -H "Authorization: Bearer $TODOIST_API_TOKEN"

A personal token carries your whole account. An OAuth app can ask for less, and the scopes are finer than most task tools offer: task:add can add tasks but cannot read or change existing data, data:read is read-only, data:read_write reads and writes, and deleting is split out into data:delete and project:delete. For a script that only files tasks from a form or a CI job, task:add is a very small thing to hand over.

Limits

The same reference publishes the limits for sync requests: for each user, 1,000 partial sync requests and 100 full sync requests in any 15-minute period, with up to 100 commands batched into one request that still counts as one. Request bodies are capped at 1 MiB. A CLI and a script share those limits because they share the account; a well-written script batches its changes rather than sending one request per task.

On the MCP side the limit you meet is different. Todoist’s Claude guide says the assistant can add up to 25 tasks in a single action, and every result the assistant reads takes room in its context. A request such as “reschedule all 300 overdue tasks” belongs in a script, or at least in batches you check as you go.

The library route, for builders

If you are building your own assistant rather than using one, you may not need MCP at all. Doist’s todoist-mcp repository↗ (opens in a new tab) publishes the same tools as a library: you import findTasksByDate or addTasks, hand each one a Todoist API client made with a token, and register them with your framework, with Vercel’s AI SDK as the documented example. The tools run in your process with the token you chose, so the scope question comes back to the API route above.

Which to use for which job

• Planning your day in Claude, ChatGPT or Cursor: the hosted MCP server, with write and delete tools set to ask first in the client.
• A coding agent that should see your list but never touch it: the CLI with td auth login --read-only, and no TODOIST_API_TOKEN in its environment.
• A coding agent that files tasks as it works: the CLI signed in normally, or the MCP server if your agent handles MCP well. Todoist’s Claude Code guide↗ (opens in a new tab) documents both.
• A form, webhook or CI step that only creates tasks: an OAuth app with task:add.
• A nightly clean-up or a migration: the API from a reviewed script, batching commands and respecting the limits.

Whatever the route, the change is made with your Todoist account. Nothing marks a task as added by an assistant rather than by you, so if you share projects, agree a habit, such as a label, that shows which is which.

When the list is shared work

Todoist is an excellent personal list. When the list is really a project that several people and their assistants work on, the questions change: who may move what, and who did it. fenbs is a board where an AI assistant joins as a member with a role, connects over MCP with a browser sign-in or a token issued by hand with the scopes you tick and an optional expiry, and appears by name in History on every change. It has one door, MCP, rather than three, and no command-line tool of its own.