Todoist MCP Server

Dry-run mode allows you to test operations and automations without making any real changes to your Todoist workspace. It validates operations using real API data and simulates mutations (create, update, delete, complete) while providing detailed logs prefixed with [DRY-RUN].

To enable Dry-Run Mode, add DRYRUN=true to your environment configuration in your MCP client config:

{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["@greirson/mcp-todoist"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here",
        "DRYRUN": "true"
      }
    }
  }
}

To disable Dry-Run Mode, remove the DRYRUN environment variable or set it to false, then restart Claude Desktop.

To install the Todoist MCP server with a one-click setup for Claude Desktop:

1. Download the todoist-mcp.mcpb file from the latest GitHub release.
2. Double-click the file or drag it onto the Claude Desktop application.
3. When prompted, enter your Todoist API token.

You can then start managing tasks by asking Claude questions like "Show me my Todoist projects".

Once the todoist-mcp.mcpb file has been built, you can install it into Claude Desktop using one of two methods:

1. Double-click the todoist-mcp.mcpb file.
2. Drag and drop the todoist-mcp.mcpb file onto the Claude Desktop application.

During the installation process, Claude Desktop will prompt you to provide your Todoist API Token.

To complete the installation, you need an API token from Todoist. Follow these steps:

1. Open Todoist (web or app).
2. Navigate to Settings > Integrations > Developer.
3. Copy your API token.
4. Paste the token into the prompt provided by Claude Desktop during installation.

Direct Link: https://app.todoist.com/app/settings/integrations/developer

For Claude Code or other MCP clients that support CLI installation, use the following command. Ensure you replace your_token with your actual Todoist API token.

claude mcp add todoist -e TODOIST_API_TOKEN=your_token -- npx @greirson/mcp-todoist

To develop or run the project from a local clone, follow these steps to install dependencies and build the project using npm:

1. Clone the repository.
2. Navigate to the project directory.
3. Install dependencies.
4. Build the project.

Ensure you have npm installed on your system.

# Clone the repository
git clone https://github.com/greirson/mcp-todoist.git

# Navigate to directory
cd mcp-todoist

# Install dependencies
npm install

# Build the project
npm run build

To create the .mcpb distribution file for the Todoist MCP server, run the build command from the project root. This generates a todoist-mcp.mcpb file in the mcpb/ directory.

npm run build:mcpb

You can customize the extension's appearance by adding a custom icon before building the package:

1. Create a PNG image (recommended dimensions: 128x128 or 256x256).
2. Name the file icon.png.
3. Place icon.png in the mcpb/ directory.
4. Rebuild the package using npm run build:mcpb to include the new icon.

If you need to manually add the Todoist server to your MCP client configuration (e.g., claude_desktop_config.json or ~/.claude.json), use the following JSON structure. Replace your_api_token_here with your actual token.

Configuration Locations:

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Claude Code: ~/.claude.json

{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["@greirson/mcp-todoist"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

The server supports two modes of operation via the TODOIST_UNIFIED_TOOLS environment variable:

1. Unified Mode: Enabled by setting TODOIST_UNIFIED_TOOLS=true. This provides a consolidated set of 19 tools designed for higher-level task management.
2. Legacy Mode: The default behavior. This provides a granular set of 60+ individual tools for fine-grained control over Todoist resources.

"No Todoist projects found" or connection errors:

• Verify your API token is correct.
• Check that the token is properly set in your claude_desktop_config.json.
• Ensure there are no extra spaces or quotes around your token.

MCP server not loading:

• Confirm the package is installed globally: npm list -g @greirson/mcp-todoist.
• Restart Claude Desktop completely.
• Check the configuration file path is correct for your operating system.
• Try the full path to the mcp-todoist binary (e.g., /Users/USERNAME/.npm-global/bin/mcp-todoist).

Permission errors:

• On macOS/Linux, you may need to create the config directory: mkdir -p ~/.config.
• Ensure Claude Desktop has permission to read the config file.