{"id":16917,"library":"todoist-mcp","title":"Todoist MCP Server","description":"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.","status":"active","version":"1.3.4","language":"javascript","source_language":"en","source_url":"https://github.com/stanislavlysenko0912/todoist-mcp-server","tags":["javascript","mcp","model-context-protocol","todoist","typescript"],"install":[{"cmd":"npm install todoist-mcp","lang":"bash","label":"npm"},{"cmd":"yarn add todoist-mcp","lang":"bash","label":"yarn"},{"cmd":"pnpm add todoist-mcp","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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`.","wrong":"const runServer = require('todoist-mcp').runServer;","symbol":"runServer","correct":"import { runServer } from 'todoist-mcp';"},{"note":"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.","wrong":"const TodoistMCPServer = require('todoist-mcp').TodoistMCPServer;","symbol":"TodoistMCPServer","correct":"import { TodoistMCPServer } from 'todoist-mcp';"},{"note":"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.","wrong":"import { TodoistConfig } from 'todoist-mcp';","symbol":"TodoistConfig","correct":"import type { TodoistConfig } from 'todoist-mcp';"}],"quickstart":{"code":"codex mcp add todoist --env API_KEY=\"your_todoist_api_token\" -- npx -y todoist-mcp\n\n# Alternatively, for persistent configuration (e.g., for Codex):\n# Create or edit ~/.codex/config.toml (or .codex/config.toml in your project root)\n# Add the following lines:\n# [mcp_servers.todoist]\n# command = \"npx\"\n# args = [\"-y\", \"todoist-mcp\"]\n# \n# [mcp_servers.todoist.env]\n# API_KEY = \"your_todoist_api_token\"","lang":"bash","description":"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."},"warnings":[{"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).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"This package requires Node.js version 18.0.0 or higher. Running it with older Node.js versions will result in execution errors.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","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.","error":"Error: Todoist API token is not set. Please set the TODOIST_API_TOKEN environment variable."},{"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.","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.","error":"node: --enable-source-maps is not allowed in NODE_OPTIONS"},{"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.","cause":"`npx` is not available in the system's PATH, or Node.js/npm is not correctly installed.","error":"TypeError: 'npx' is not recognized as an internal or external command, operable program or batch file."}],"ecosystem":"npm","meta_description":null}