Todoist MCP Server

1.3.4 · active · verified Wed Apr 22

Todoist MCP Server is a command-line interface (CLI) application that integrates various AI assistants (like Claude, Cursor, Codex, Gemini) with Todoist, enabling natural language task management. It acts as a Model Context Protocol (MCP) server, translating AI commands into Todoist API actions. Currently at version 1.3.4, the package does not explicitly define a release cadence but appears to be actively maintained. Key differentiators include full access to the Todoist REST API v2 and Sync API via natural language, support for batch processing of tasks, the ability to search by name rather than ID, and 'Smart Context' which pre-loads project and label information to the AI, reducing the need for explicit tool calls. It provides a robust set of tools for managing tasks, projects, sections, comments, and labels within Todoist through conversational AI interactions.

Common errors

```
Error: Todoist API token is not set. Please set the TODOIST_API_TOKEN environment variable.
```
cause The required `API_KEY` (or `TODOIST_API_TOKEN`) environment variable, which holds your Todoist authentication token, was not provided when the server was launched.

fix Ensure the `API_KEY` environment variable is correctly set and passed to the `npx todoist-mcp` command. For example, `env: { "API_KEY": "your_token" }` in a JSON config or `--env API_KEY=your_token` on the command line.
```
node: --enable-source-maps is not allowed in NODE_OPTIONS
```
cause This error typically indicates an incompatibility with how Node.js is being invoked, often due to an older `npx` or `npm` version or conflicting `NODE_OPTIONS` from a global config.

fix Try updating `npm` (`npm install -g npm@latest`) and `npx`. If the issue persists, explicitly clearing `NODE_OPTIONS` before running `npx` (e.g., `NODE_OPTIONS='' npx -y todoist-mcp`) might resolve it, or check your shell's environment for conflicting settings.
```
TypeError: 'npx' is not recognized as an internal or external command, operable program or batch file.
```
cause `npx` is not available in the system's PATH, or Node.js/npm is not correctly installed.

fix Ensure Node.js and npm are properly installed and their binaries are accessible in your system's PATH. Reinstalling Node.js is often the simplest fix.

Warnings

gotcha A Todoist API token is absolutely required for the server to function. Without it, the server cannot authenticate with Todoist and will not be able to manage tasks or projects.
Fix: Obtain your API token from Todoist Settings -> Integrations -> Developer section and provide it via the `API_KEY` environment variable during server execution (e.g., `env: { "API_KEY": "your_token" }` in config, or `--env API_KEY=token` in CLI commands).
breaking This package requires Node.js version 18.0.0 or higher. Running it with older Node.js versions will result in execution errors.
Fix: Update your Node.js environment to version 18.0.0 or newer. Use `nvm` or a similar tool to manage Node.js versions if needed.
gotcha Configuration methods vary significantly across different AI platforms (e.g., Claude Desktop, Claude Code, Cursor, Codex, Gemini CLI). Ensure you follow the specific instructions for your AI client.
Fix: Refer to the 'Configuration' section in the `todoist-mcp` README for platform-specific setup instructions and examples, paying close attention to command syntax and file paths.
gotcha The package is designed to be run via `npx` as a command-line tool. Attempting to `import` or `require` it directly into another application for programmatic use is not the primary intended interaction pattern and may not be fully supported or documented.
Fix: Interact with `todoist-mcp` by configuring your AI client to execute `npx -y todoist-mcp` as a subprocess, passing necessary environment variables like `API_KEY`.

Install

npm install todoist-mcp npm
yarn add todoist-mcp yarn
pnpm add todoist-mcp pnpm

Imports

runServer
wrong:
```
const runServer = require('todoist-mcp').runServer;
```
correct:
```
import { runServer } from 'todoist-mcp';
```
This package is primarily a CLI application run via `npx`. Direct programmatic imports like this are not the standard or documented use case for end-users, but `runServer` might represent an internal entry point if one were to embed or extend the server programmatically. Always prefer `npx todoist-mcp`.
TodoistMCPServer
wrong:
```
const TodoistMCPServer = require('todoist-mcp').TodoistMCPServer;
```
correct:
```
import { TodoistMCPServer } from 'todoist-mcp';
```
Similar to `runServer`, `TodoistMCPServer` would represent the core server class if consumed as a library. For typical usage, the server is launched via a shell command and configured through AI platform settings, not directly instantiated in user code.
TodoistConfig
wrong:
```
import { TodoistConfig } from 'todoist-mcp';
```
correct:
```
import type { TodoistConfig } from 'todoist-mcp';
```
If programmatic interaction were needed, `TodoistConfig` would be a hypothetical type definition for the server's configuration parameters. This is for TypeScript type safety; actual runtime config is typically via environment variables (`API_KEY`) as shown in the README, or JSON/TOML files.

Quickstart

This quickstart demonstrates how to add the Todoist MCP Server to the Codex AI client, either via a CLI command or by configuring a TOML file. It sets the required `API_KEY` environment variable for authentication with Todoist.

codex mcp add todoist --env API_KEY="your_todoist_api_token" -- npx -y todoist-mcp

# Alternatively, for persistent configuration (e.g., for Codex):
# Create or edit ~/.codex/config.toml (or .codex/config.toml in your project root)
# Add the following lines:
# [mcp_servers.todoist]
# command = "npx"
# args = ["-y", "todoist-mcp"]
# 
# [mcp_servers.todoist.env]
# API_KEY = "your_todoist_api_token"

view raw JSON →