todoist-mcp: A Tool Library for Todoist, With an MCP Server Attached
A set of tools to connect to AI agents, to allow them to use Todoist on a user's behalf. Includes MCP support.
At a glance
- What is it?
- Doist ships a TypeScript package that exposes Todoist operations as AI-callable tools, importable directly or served over MCP. The design bet is reusable tools, not MCP-only ones, and the README is candid that the tool set is still small.
- Who is it for?
- Adopt it if you want Todoist actions inside an AI client and you are comfortable with OAuth against the hosted endpoint at https://ai.todoist.net/mcp, or if you are building your own assistant and want the tool definitions rather than the server. Do not adopt it if you need a broad, finished tool surface: the README says the project is in its early stages.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Problem: Todoist Has No Native Seat in an AI Chat Window
An AI assistant that can reason about your week is not much use if it cannot see or change your task list. todoist-mcp exists to close that gap. It is a library of tools that let an AI agent read and modify a Todoist account on the user's behalf, and it can be consumed two ways: as an MCP server for clients that speak that protocol, or imported directly into a project that has its own conversational interface. The audience is split accordingly. One group is end users who want Todoist available inside Claude Desktop, Cursor, Claude Code or VS Code. The other is developers building an assistant who would rather not write Todoist tool definitions from scratch. The README states the goal plainly: a small set of tools that enable complete workflows rather than atomic actions, balancing flexibility against efficiency for the model. That is a real design position, and it is the thing to judge the project against.
Tools First, MCP Second: How the Package Is Put Together
The architecture follows from one sentence in the README: tools are not written specifically for use in an MCP server. A tool is a plain object with an execute method that takes arguments plus a Todoist client. The MCP server is one consumer of those objects; Vercel's AI SDK is another, and the README uses streamText as its worked example. The data flow is short. You construct a TodoistApi client from @doist/todoist-sdk with an API key, wrap each tool so that execute(args, todoistClient) is called with the client bound, and hand the wrapped tools to your model. The MCP path swaps that wiring for the official @modelcontextprotocol/server package, which serves the same tools over the protocol. Two details are worth noting. First, the server includes search and fetch tools that follow the OpenAI MCP specification, returning JSON-encoded results shaped for OpenAI's requirements while staying usable elsewhere. Second, the README mentions MCP Apps: interactive widgets rendered inline in chat interfaces, so a task list can appear as something other than plain text. The widget architecture and build pipeline live in docs/mcp-apps.md, which the README does not reproduce.
Getting It Running: npx, OAuth, and a Remote Endpoint
For the MCP server the shortest path is npx @doist/todoist-mcp. Doist also runs a hosted streamable HTTP endpoint at https://ai.todoist.net/mcp, and most of the client instructions point there. Claude Desktop is configured through Settings, then Connectors, then Add custom connector, where you enter that URL and complete OAuth. Cursor uses a JSON config at ~/.cursor/mcp.json or .cursor/mcp.json, with an mcpServers entry whose command is npx and whose args are ["-y", "mcp-remote", "https://ai.todoist.net/mcp"]. Claude Code has two routes: the official plugin, installed via /plugin marketplace add doist/todoist-mcp followed by /plugin install todoist@doist, or the manual form claude mcp add --transport http todoist https://ai.todoist.net/mcp, after which you run /mcp inside a session to authenticate. VS Code goes through the Command Palette, MCP: Add Server, with HTTP transport and a servers entry containing type http and the same URL. Any other client can use npx -y mcp-remote https://ai.todoist.net/mcp. Note that OAuth runs in the browser the first time you invoke a Todoist tool, and that the hosted URL is a service Doist operates, not something you self-host by pointing at it. For local work, npm start builds and launches the MCP inspector, npm run dev rebuilds and restarts on change, and npm run tool:list enumerates the tools available for direct execution.
Running Tools Without an AI in the Loop
The most useful thing in the README for anyone evaluating this package is the direct execution path. npm run tool -- <tool-name> '<json-args>' runs a single tool from the command line, bypassing MCP entirely. The README gives one example and it is a good one: npm run tool -- user-info '{}' confirms which Todoist account the current TODOIST_API_KEY is connected to. That matters because every other operation inherits that key's permissions. The run-tool script reads TODOIST_API_KEY from a .env file, which npm run setup creates from .env.example. The README's own warning is worth repeating: use a test account or a temporary project when running write operations, because there is no dry-run flag described anywhere in the material. The double dash before the tool name is not optional; without it npm swallows the arguments instead of forwarding them to scripts/run-tool.ts. This CLI is also the cheapest way to check whether a tool's argument schema matches what you expect before you wire it into a model, where a schema mismatch shows up as a confused assistant rather than an error message.
Where the Project Is Thin, and Where It Is the Wrong Choice
The README says the project is in its early stages and that you should expect more or better tools soon. Take that at face value. The complete tool list lives in the src/tools directory rather than in the README, which means the documented surface is a moving target and this article cannot enumerate it. If your workflow depends on a Todoist capability that no tool covers, you are writing it yourself against @doist/todoist-sdk, and the MCP server gives you no help there. The design choice to favor workflow-level tools over atomic actions is a genuine trade-off: fewer tools to route between, but less granularity when a model needs one specific operation that the composite tool does not expose. There is also a hosting question. The documented MCP setup leans on https://ai.todoist.net/mcp, so your task data passes through a Doist-operated service, and authentication is OAuth against that service. If your constraint is that no third party sits between your assistant and your task data, the hosted endpoint is the wrong tool; the npm package and the local server path are the parts you would use instead. Finally, the OpenAI compatibility tools return JSON-encoded results shaped for OpenAI's requirements, which is a compatibility layer rather than a neutral format, and clients outside that ecosystem may find the shape less convenient than the generic tools.
Alternatives: Writing Your Own Tools Against the Todoist SDK
The clearest alternative is not another MCP server but the layer underneath this one. @doist/todoist-sdk is the TypeScript client this project depends on, and it exposes the Todoist API directly. Building on it yourself means you decide the tool boundaries: one tool per API call, or composite tools shaped around your own workflows, or a mix. You also control the return format instead of inheriting JSON-encoded results tuned for one vendor's protocol, and you avoid any dependency on the hosted MCP endpoint. The cost is that you write and maintain the tool definitions, the argument schemas, and the descriptions the model reads to decide when to call them. That last part is the real work: a tool the model misroutes is worse than no tool. todoist-mcp's value is that Doist has already made those decisions and documented the reasoning in docs/tool-design.md. If you disagree with those decisions, forking or reimplementing is straightforward because the tools are plain objects with an execute method, not a framework you have to adopt wholesale. The import path is a genuine middle ground: npm install @doist/todoist-mcp, then use the tools in your own interface without touching MCP at all.
Maintenance, Releases and the MIT Licence
Releases are automated with release-please, driven by Conventional Commits. A feat: commit produces a minor bump, fix: a patch, and feat!: or fix!: a major bump; docs:, chore: and ci: do not move the version. Commits landing on main cause release-please to open or update a release PR containing the version bump and changelog, and merging that PR creates the tag and triggers the publish workflow. For a consumer this means version numbers carry meaning: a major bump signals a breaking change to tool signatures or behaviour, which is exactly the kind of change that can silently break a prompt that names tools. The published cadence is visible in the recent tags, with v13.2.4, v13.2.3 and v13.2.2 all landing within about a week of each other, so patch releases arrive often. Pin your version and read the changelog before moving a major. The project is MIT licensed, which is permissive and places few obligations on how you redistribute or embed it. That is a statement about the licence text, not legal advice; if you are shipping this inside a commercial product, have someone qualified read the terms. Note also that the licence covers this package, not the hosted endpoint at ai.todoist.net or your Todoist account, which are governed by separate terms.
Editorial conclusion
Adopt it if you want Todoist actions inside an AI client and you are comfortable with OAuth against the hosted endpoint at https://ai.todoist.net/mcp, or if you are building your own assistant and want the tool definitions rather than the server. Do not adopt it if you need a broad, finished tool surface: the README says the project is in its early stages. Before wiring anything to a real account, run npm run tool -- user-info '{}' to confirm which Todoist account your TODOIST_API_KEY points at, and check src/tools for the current tool list.
Community notes