todoist-mcp

library0.4.0jsnpmunverified

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.

llm-agents crm-productivity

npm install todoist-mcp

github ↗package ↗

INSTALL

IMPORT

SIG · TODOIST-MCP

todoist-mcp

llm-agentsjavascriptv0.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

runServer

✓ import { runServer } from 'todoist-mcp';

✗ const runServer = require('todoist-mcp').runServer;

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

✓ import { TodoistMCPServer } from 'todoist-mcp';

✗ const TodoistMCPServer = require('todoist-mcp').TodoistMCPServer;

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

✓ import type { TodoistConfig } from 'todoist-mcp';

✗ import { 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.

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"

todoist-mcp --version

Debug

Known issues

gotchaA 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).

affects: >=1.0.0

breakingThis 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.

affects: >=1.0.0

gotchaConfiguration 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.

affects: >=1.0.0

gotchaThe 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`.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Todoist API token is not set. Please set the TODOIST_API_TOKEN environment variable.

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

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.

`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.

Upgrade

Version history

0.4.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

48 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/stanislavlysenko0912/todoist-mcp-server ↗

packagehttps://www.npmjs.com/package/todoist-mcp ↗