Todoist MCP: connecting AI agents to a real task account

The gap between a chat window and an actual task list

An assistant that can talk about your week is not the same as an assistant that can put Thursday's invoice reminder into the right project. The README frames the project around that second job: tools that let an LLM "access and modify a Todoist account on the user's behalf." The audience is narrow and specific. It is developers building conversational interfaces who want Todoist actions inside them, and end users of Claude Desktop, Cursor, Claude Code or VS Code who want their existing client to reach Todoist without writing glue code. If you only want a faster way to type tasks yourself, this is not the layer you are looking for; it is plumbing between an agent and the Todoist API.

Tools first, MCP server second

The design decision that separates this from a plain MCP wrapper is stated plainly: tools are not written specifically for the MCP server and can be imported directly into other projects. The README example shows the shape. Each tool exposes an execute function that takes arguments and a Todoist client, and you wrap it to bind your own client instance before handing it to a framework such as Vercel's AI SDK. That means the same findTasksByDate implementation can serve an MCP client, a custom chat app, or a script.

On the server side the dependency chain is short: the official @modelcontextprotocol/server package for the protocol, and @doist/todoist-sdk as the API client. The package also declares search and fetch tools that follow the OpenAI MCP specification, returning JSON-encoded results aimed at that protocol while staying usable by other MCP clients. The README notes the goal is tools that enable complete workflows rather than atomic actions, which is a deliberate trade: fewer, larger tools are easier for a model to choose between, but harder to compose if your workflow does not match the ones the maintainers picked.

Installing the library and wiring a first tool

If you are building your own interface, the package installs from npm and the README's example imports two tools plus the Todoist API client. Note that the tools do not hold credentials themselves; you construct a TodoistApi with your key and wrap each tool so execute receives that client.

npm install @doist/todoist-mcp

import { findTasksByDate, addTasks } from '@doist/todoist-mcp'
import { TodoistApi } from '@doist/todoist-sdk'
import { streamText } from 'ai'

const client = new TodoistApi(process.env.TODOIST_API_KEY)

const result = streamText({
    model: yourModel,
    system: 'You are a helpful Todoist assistant',
    tools: {
        findTasksByDate: wrapTool(findTasksByDate, client),
        addTasks: wrapTool(addTasks, client),
    },
})

The README defines wrapTool as a small helper that spreads the tool and overrides execute to call tool.execute(args, todoistClient). The client reads TODOIST_API_KEY from the environment. The package requires Node 24 or newer and npm 11 or newer, which is a hard floor: on an older runtime the install will not get you a working server.

Connecting an existing client over HTTP

For clients that speak MCP already, the shortest path is the hosted streamable HTTP endpoint rather than a local process. The README gives https://ai.todoist.net/mcp as the primary URL. Claude Desktop takes it through Settings, then Connectors, then Add custom connector, followed by OAuth. Cursor needs a config file at ~/.cursor/mcp.json or .cursor/mcp.json that launches mcp-remote against that URL.

{
    "mcpServers": {
        "todoist": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "https://ai.todoist.net/mcp"]
        }
    }
}

Claude Code has two routes. The README calls the official plugin the fastest: `/plugin marketplace add doist/todoist-mcp` followed by `/plugin install todoist@doist`, with OAuth opening in the browser the first time a Todoist tool runs. The manual route is `claude mcp add --transport http todoist https://ai.todoist.net/mcp`, after which you launch claude, run /mcp, and select the todoist server to authenticate. VS Code uses the Command Palette entry MCP: Add Server with HTTP transport and a servers block containing type http and the same URL. Any other client can use `npx -y mcp-remote https://ai.todoist.net/mcp`. There is also a local option: `npx @doist/todoist-mcp` runs the server from the published package.

Running tools directly, and why the README warns you

The repository ships a script for exercising tools without an MCP client, which is the practical way to check what a tool will do before an agent does it. From a clone, `npm run tool:list` prints the available tools, and `npm run tool -- <tool-name> '<json-args>'` runs one. The README's own example is a read before a write.

npm run tool -- user-info '{}'

That call reports which Todoist account the current TODOIST_API_KEY is connected to. The key comes from a .env file created from .env.example by `npm run setup`, and .env.example contains a single entry, TODOIST_API_KEY. The README is explicit that write operations should be pointed at a test account or a temporary project so real data is not modified. This is not boilerplate caution: an agent holding a valid key can change a live account, and the direct-run script exists precisely so you can see the effect on purpose rather than by accident.

Limitations the project states about itself

The README says the project is in its early stages and that more or better tools should be expected. That is the honest limitation, and it has consequences. Tool names, argument shapes and the set of available operations are all moving; the release history shows a steady stream of v13.2.x patches, and the project uses release-please with Conventional Commits, so a `feat!:` or `fix!:` commit produces a major version bump. Pinning a version is the only way to keep an agent's tool definitions stable across upgrades.

The second limitation is scope. The README points at src/tools for the complete list rather than enumerating it, so how much of Todoist you can actually reach is defined by that directory, not by the API's surface. If your workflow depends on a Todoist feature no tool covers, the library will not invent it. The third is the runtime floor: Node 24 and npm 11 are declared in package.json, so environments pinned to older Node releases cannot run the server locally and should use the hosted endpoint instead.

Where this sits against calling the Todoist API yourself

The obvious alternative is to skip the MCP layer and write against the Todoist API directly, using @doist/todoist-sdk, which this project already depends on. The difference is what each side owns. With the SDK alone you own the tool definitions, the descriptions the model reads, the argument schemas, and the choice of which operations to expose; you get exactly the surface you designed and nothing you did not. With todoist-mcp you inherit the maintainers' tool design, documented in docs/tool-design.md, including the decision to favor complete workflows over atomic actions. That saves the work of teaching a model when to call what, and it costs you control over granularity. A team that needs one narrow operation, such as creating a task in a fixed project, will find the SDK route shorter. A team that wants an agent to handle a range of task operations across clients will find the MCP server does work they would otherwise repeat per client.

Licence, maintenance and the cost of upgrading

The package is MIT licensed and published with provenance, so you can read the source, fork it, and ship it inside a commercial product. MIT imposes no copyleft obligation on your own code; it does require that the copyright notice and licence text travel with copies of the software. That is a general property of the licence, not legal advice for your situation.

The repository is not archived, and the last push was on 2026-09-10, with v13.2.4 released the same day. Upgrade cost is mostly version pinning and changelog reading. Because release-please derives versions from commit prefixes, the CHANGELOG.md file is the place to look before bumping, and a major bump is the signal that a tool contract changed. If you consume the hosted endpoint rather than the npm package, you do not control when the server changes underneath your client, which shifts the upgrade risk from your lockfile to Todoist's deployment schedule.

Editorial conclusion

Adopt it if you already live in Todoist and want an agent to file, find and update tasks without leaving the chat client, and if you can run Node 24 or use the hosted endpoint at https://ai.todoist.net/mcp. Skip it if you need a stable tool surface today: the README states the project is in its early stages, so tool names and arguments can move between the v13 releases. Before pointing it at a live account, run `npm run tool -- user-info '{}'` to confirm which account your TODOIST_API_KEY reaches, and read src/tools and docs/tool-design.md to see exactly which operations exist.

Frequently asked questions

Official sources

1. Doist/todoist-mcp on GitHub
2. Issues
3. License: MIT
4. README
5. Releases