Todoist MCP Server

An MCP (Model Context Protocol) server that connects Claude with Todoist for complete task and project management through natural language.

Installation

Claude Desktop (One-Click Install)

1. Download todoist-mcp.mcpb from the latest release
2. Double-click the file (or drag onto Claude Desktop)
3. Enter your Todoist API token when prompted
4. Start chatting: _"Show me my Todoist projects"_

Claude Code / Other MCP Clients

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

<details>
<summary>Manual JSON configuration</summary>

Add to your MCP client config (claude_desktop_config.json, ~/.claude.json, etc.):

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

Config 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

</details>

Features

- 19 MCP Tools for complete Todoist management
- Task Management: Create, update, delete, complete, reopen tasks with priorities, due dates, labels
- Bulk Operations: Process multiple tasks efficiently
- Subtasks: Hierarchical task management with completion tracking
- Projects & Sections: Full organization support
- Labels, Filters, Reminders: Pro/Business features supported
- Natural Language: Quick add with Todoist's natural language parsing
- Dry-Run Mode: Test operations without making changes

Dry-Run Mode

Dry-run mode allows you to test operations and automations without making any real changes to your Todoist workspace. This is perfect for testing, debugging, learning the API, or validating automation scripts before running them for real.

How to Enable Dry-Run Mode

Add DRYRUN=true to your environment configuration:

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

What Dry-Run Mode Does

- Validates Operations: Uses real API data to validate that operations would succeed
- Simulates Mutations: Create, update, delete, and complete operations are simulated (not executed)
- Real Data Queries: Read operations (get tasks, projects, labels) use the real API
- Detailed Logging: Shows exactly what would happen with clear [DRY-RUN] prefixes
- Error Detection: Catches the same errors that would occur in real execution

Use Cases

- Testing Automations: Validate complex bulk operations before executing
- Learning the API: Explore functionality without fear of making unwanted changes
- Debugging Issues: Understand what operations would be performed
- Safe Experimentation: Try new workflows without affecting your actual tasks
- Training and Demos: Show how operations work without modifying real data

Example Usage

With dry-run mode enabled, operations show what would happen:

You: "Create a task called 'Test Task' in my Work project"
Response:

[DRY-RUN] Dry-run mode enabled - mutations will be simulated

[DRY-RUN] Would create task: "Test Task" in project 2203306141, section none
Task created successfully (simulated):

ID: 100001

Title: Test Task

Project: Work (2203306141)

Priority: 4 (Normal)

Supported Operations

All 19 MCP tools support dry-run mode:

- Task creation, updates, completion, and deletion
- Subtask operations and hierarchy changes
- Bulk operations across multiple tasks
- Project and section creation
- Label management operations
- Reminder CRUD operations
- Comment creation

Disabling Dry-Run Mode

Remove the DRYRUN environment variable or set it to false, then restart Claude Desktop to return to normal operation mode.

Tools Overview

The server provides 19 MCP tools for complete Todoist management:

| Tool | Actions | Description |
| ----------------------- | ----------------------------------------------------------------------- | ------------------------------- |
| todoist_task | create, get, update, delete, complete, reopen, quick_add | Complete task management |
| todoist_task_bulk | bulk_create, bulk_update, bulk_delete, bulk_complete | Efficient multi-task operations |
| todoist_subtask | create, bulk_create, convert, promote, hierarchy | Hierarchical task management |
| todoist_project | create, get, update, delete, archive, collaborators | Project CRUD and sharing |
| todoist_project_ops | reorder, move_to_parent, get_archived | Advanced project operations |
| todoist_section | create, get, update, delete, move, reorder, archive | Section management |
| todoist_label | create, get, update, delete, stats | Label management with analytics |
| todoist_comment | create, get, update, delete | Task/project comments |
| todoist_reminder | create, get, update, delete | Reminder management (Pro) |
| todoist_filter | create, get, update, delete | Custom filters (Pro) |
| todoist_collaboration | invitations, notifications, workspace operations | Team collaboration features |
| todoist_user | info, productivity_stats, karma_history | User profile and stats |
| todoist_utility | test_connection, test_features, test_performance, find/merge duplicates | Testing and utilities |
| todoist_activity | get_log, get_events, get_summary | Activity audit trail |
| todoist_task_ops | move, reorder, close | Advanced task operations |
| todoist_completed | get, get_all, get_stats | Completed task retrieval |
| todoist_backup | list, download | Automatic backup access |
| todoist_notes | create, get, update, delete | Project notes (collaborators) |
| todoist_shared_labels | create, get, rename, remove | Workspace labels (Business) |

For detailed tool documentation with parameters and examples, see TOOLS_REFERENCE.md.

Troubleshooting

Common Issues

"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: /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

Usage Examples

Project & Section Setup

"Show me all my projects"
"Create a new project called 'Work Tasks'"
"Create a section called 'In Progress' in project 12345"
"Show me sections in the Work Tasks project"

Task Creation & Management

```
"Create task 'Team Meeting' in project 12345"
"Add task 'Review PR' due tomorrow with labels ['Code Review', 'Urgent']"
"Create high priority task with deadline 2024-12-25"
"Update meeting task to be in section 67890"
"Mark the PR review task as complete"