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 Code / Other MCP Clients

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

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

{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["@kleprevost/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

Features

• 20 MCP Tools for complete Todoist management
• Task Management: Create, update, delete, complete, reopen tasks with priorities, due dates, labels
• Task Enrichment: Every task response includes section_name and created_at (YYYY-MM-DD)
• Project Briefing: Pre-bucketed task views — overdue, due today, due this week, needs discussion, someday, other
• 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

Task Enrichment

Every task response from todoist_task (get) and todoist_get_briefing includes two enrichment fields:

• section_name — the name of the section the task belongs to, or null if unsectioned. Resolved via the Todoist sections API with a 30-second cache; no extra API calls when retrieving multiple tasks.
• created_at — the date the task was created, in YYYY-MM-DD format (local time). Read directly from the Todoist API's addedAt field; no additional API calls required.

These fields make it straightforward to group tasks visually or flag tasks that have been sitting open for a long time without a due date.

Project Briefing

The todoist_get_briefing tool returns all active tasks for a project pre-organized into six named buckets — no filter logic required on the caller side:

| Bucket | Definition | |---|---| | overdue | Due date is before today | | due_today | Due date is today | | due_this_week | Due within the next 7 days (excluding today) | | needs_discussion | Labeled needs-discussion, any due date | | someday | Labeled someday, no due date | | other | No due date and no special label |

A task can appear in multiple buckets (e.g. overdue + needs-discussion). Buckets with zero tasks are always present in the response so the caller knows they were checked. Each task includes section_name and created_at.

"Give me a briefing for my Work project"
"Get briefing for project 2349336895"

Dry-Run Mode

Dry-run mode allows you to test operations and automations without making any real changes to your Todoist workspace.

How to Enable

Add DRYRUN=true to your environment configuration:

{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["@kleprevost/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

Tools Overview

The server provides 20 MCP tools for complete Todoist management:

| Tool | Actions / Parameters | 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) | | todoist_get_briefing | project_id (required) | Pre-bucketed project task briefing |

Usage Examples

Project Briefing

"Give me a briefing for my Work project"
"Briefing for project 2349336895"

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"

# Task duration for time blocking
"Create task 'Deep work session' with 90 minute duration"
"Update task 'Meeting' to have a 2 day duration"

# Task identification by ID (more reliable than name search)
"Get task with ID 1234567890"
"Update task ID 1234567890 to priority 4"
"Complete task with ID 1234567890"
"Reopen task with ID 1234567890"
"Delete task ID 1234567890"

Quick Add

The Quick Add tool parses natural language text like the Todoist app, supporting multiple features in a single command:

"Quick add: Buy groceries tomorrow #Shopping @errands p1"
"Quick add: Review PR next Monday #Work @code-review p2 //Check error handling"
"Quick add: Call mom {deadline in 3 days}"
"Quick add: Team meeting today at 2pm #Work @meetings with reminder 1 hour before"

Quick Add Syntax:

• Due dates: Natural language dates like "tomorrow", "next Friday", "Jan 23", "in 3 days"
• Projects: #ProjectName (no spaces in project names)
• Labels: @label (e.g., "@urgent", "@work")
• Assignees: +name (for shared projects)
• Priority: p1 (urgent), p2, p3, p4 (lowest)
• Deadlines: {in 3 days} or {March 15}
• Descriptions: //your description here (must be at the end)

Subtask Management

"Create subtask 'Prepare agenda' under task 'Team Meeting'"
"Create multiple subtasks for 'Launch Project': 'Design UI', 'Write tests', 'Deploy'"
"Convert task 'Code Review' to a subtask of 'Release v2.0'"
"Promote subtask 'Bug Fix' to a main task"
"Show me the task hierarchy for 'Launch Project' with completion tracking"

Bulk Operations

"Create multiple tasks for project launch: 'Design mockups', 'Write documentation', 'Set up CI/CD'"
"Update all high priority tasks to be due next week"
"Complete all tasks containing 'review' in project 12345"
"Delete all tasks with priority 1 that are overdue"

Label Management

"Show me all my labels"
"Create a new label called 'Urgent' with red color"
"Update the 'Work' label to be blue and mark as favorite"
"Delete the unused 'Old Project' label"
"Get usage statistics for all my labels"

Testing & Validation

"Test my Todoist connection"
"Run basic tests on all Todoist features"
"Benchmark Todoist API performance with 10 iterations"

Troubleshooting

"No Todoist projects found" or connection errors:

• Verify your API token is correct at Todoist integrations settings
• Check that the token is properly set in your MCP client config
• Ensure there are no extra spaces or quotes around your token

MCP server not loading:

• Confirm the package is installed: npm list -g @kleprevost/mcp-todoist
• Restart your MCP client completely
• Check the configuration file path is correct for your operating system

Development

Building from source

git clone https://github.com/kleprevost/mcp-todoist.git
cd mcp-todoist
npm install
npm run build

Development Commands

npm run watch        # Watch for changes and rebuild
npm run test         # Run tests
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Run tests with coverage
npm run lint         # Lint code
npm run lint:fix     # Fix linting issues
npm run format       # Format code

Changelog

See CHANGELOG.md for a detailed history of all changes.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Issues and Support

File an issue on the GitHub repository.