Todoist MCP Server

MCP server enabling programmatic Todoist task and project management through an optimized tool set using Todoist REST API v1. Integrates seamlessly with Claude Desktop and other MCP-compatible clients.

Table of Contents

• Features

• Prerequisites

• Installation

• Configuration

• Available Tools

• Rate Limiting

• Development

• Contributing

• License

Related MCP server: Todoist MCP Server

Features

• 8 Core Tools: Comprehensive task and project management

  • Tasks (CRUD + complete/uncomplete)

  • Bulk Tasks (batch operations on up to 50 tasks)

  • Projects (CRUD + archive/unarchive)

  • Sections (organize tasks within projects)

  • Comments (with file attachment support)

  • Filters (custom task queries)

  • Reminders (relative, absolute, location-based)

  • Labels (personal and shared label management)

• Natural Language Dates: "tomorrow", "every Monday", "next Friday at 3pm"

• Deadline Support: Set completion deadlines distinct from due dates

• Batch Operations: Execute up to 100 operations per request via Sync API

• Smart Rate Limiting: Token bucket algorithm with automatic retry

• Type Safety: Full TypeScript implementation with Zod validation

• Comprehensive Testing: Contract and integration test coverage

Prerequisites

• Node.js 18 or higher

• Todoist account (Sign up free)

• Todoist API token (Get yours here)

• Any of the popular MCP clients, such as:

  • Claude Desktop

  • Claude Code CLI

  • Codex CLI

  • Cursor IDE or CLI

  • Raycast MCP Extension

  • Any other MCP-compatible client

Installation

This MCP server is deployed as a remote HTTP service. No local installation required - just configure your MCP client to connect to the HTTP endpoint.

For Deployment

If you want to deploy your own instance:

1. Fork this repository

2. Deploy to Vercel (button below)

3. Configure TODOIST_API_TOKEN in Vercel environment variables

Configuration

MCP Clients

Configure your MCP client with the HTTP transport:

Claude Desktop / Claude Code

Add to your MCP settings file:

macOS: ~/.claude/settings.json Windows: %APPDATA%\.claude\settings.json Linux: ~/.config/claude/settings.json

{
  "mcpServers": {
    "todoist": {
      "transport": {
        "type": "http",
        "url": "https://todoist.uberfolks.ca/mcp"
      }
    }
  }
}

For local development:

{
  "mcpServers": {
    "todoist": {
      "transport": {
        "type": "http",
        "url": "http://localhost:3000/mcp"
      }
    }
  }
}

Available Tools

todoist_tasks

Complete task management with create, get, update, delete, list, complete, uncomplete, and list_completed actions. Supports natural language dates, deadlines, priorities, labels, recurring tasks, and querying completed tasks within time-bounded windows.

Key parameters: action, task_id, content, due_date, due_string, deadline, priority, labels, project_id, completed_query_type, since, until

Completed tasks querying:

• list_completed action retrieves completed tasks

• Query by completion date (3-month window) or due date (6-week window)

• Supports filtering by project, section, workspace, labels, and more

• Cursor-based pagination for large result sets

• Example: Query all tasks completed in September with Work label

  {
    "action": "list_completed",
    "completed_query_type": "by_completion_date",
    "since": "2025-09-01T00:00:00Z",
    "until": "2025-09-30T23:59:59Z",
    "filter_query": "@Work",
    "limit": 50
  }

todoist_projects

Project management with create, get, update, delete, list, archive, and unarchive actions. Organize work with hierarchical projects and custom views.

Key parameters: action, project_id, name, color, is_favorite, view_style

todoist_sections

Section management within projects for better task organization. Create, get, update, delete, list, and reorder sections.

Key parameters: action, section_id, project_id, name, order

todoist_comments

Add and manage comments on tasks and projects with file attachment support (up to 15,000 characters).

Key parameters: action, comment_id, task_id, project_id, content, attachment

todoist_filters

Create and manage custom filters for advanced task queries. List, create, update, delete, and query filters.

Key parameters: action, filter_id, name, query, color, is_favorite

todoist_reminders

Set reminders for tasks with three types: relative (X minutes before due), absolute (specific datetime), and location-based (geofenced).

Key parameters: action, reminder_id, item_id, type, minute_offset, due, loc_lat, loc_long

todoist_labels

Manage personal and shared labels with create, get, update, delete, list, rename, and remove actions. Includes caching for optimal performance.

Key parameters: action, label_id, name, color, is_favorite, order

todoist_bulk_tasks

Perform bulk operations on up to 50 tasks simultaneously. Supports update, complete, uncomplete, and move operations with automatic deduplication and partial execution mode.

Key parameters: action, task_ids (1-50 items), project_id, section_id, labels, priority, due_string, deadline_date

Supported Actions:

• update - Modify task fields (due date, priority, labels, etc.)

• complete - Mark multiple tasks as done

• uncomplete - Reopen completed tasks

• move - Change project/section/parent for multiple tasks

Usage Examples:

// Bulk update due dates for 5 tasks
{
  "action": "update",
  "task_ids": ["7654321", "7654322", "7654323", "7654324", "7654325"],
  "due_string": "tomorrow"
}

// Bulk complete 10 tasks
{
  "action": "complete",
  "task_ids": ["7654321", "7654322", "7654323", "7654324", "7654325",
               "7654326", "7654327", "7654328", "7654329", "7654330"]
}

// Bulk move 7 tasks to different project
{
  "action": "move",
  "task_ids": ["7654321", "7654322", "7654323", "7654324", "7654325",
               "7654326", "7654327"],
  "project_id": "2203306141"
}

// Bulk update multiple fields for 8 tasks
{
  "action": "update",
  "task_ids": ["7654321", "7654322", "7654323", "7654324",
               "7654325", "7654326", "7654327", "7654328"],
  "priority": 2,
  "labels": ["urgent", "work"],
  "deadline_date": "2025-12-31"
}

Limitations:

• Maximum 50 unique tasks per operation (after deduplication)

• Cannot modify content (task title), description, or comments in bulk

• All tasks receive the same field updates

• Performance: <2 seconds for 50-task operations

Response Structure:

• Individual results for each task (success/failure)

• Summary counts (total, successful, failed)

• Automatic deduplication metadata

• Execution time tracking

Rate Limiting

The server implements intelligent rate limiting to respect Todoist API constraints:

• REST API: 300 requests/minute (token bucket: 300 capacity, 5 tokens/sec refill)

• Sync API: 50 requests/minute (token bucket: 50 capacity, ~0.83 tokens/sec refill)

• Automatic Retry: Exponential backoff on 429 responses

• Batch Operations: Use for bulk updates to minimize API calls

Development

Prerequisites

• Node.js 18+

• Vercel CLI: npm install -g vercel

• Todoist API token

Local Setup

1. Clone the repository:

   git clone https://github.com/shayonpal/mcp-todoist.git
   cd mcp-todoist

2. Install dependencies:

   npm install

3. Create .env.local:

   echo "TODOIST_API_TOKEN=your_token_here" > .env.local

4. Start development server:

   vercel dev

   Server runs at http://localhost:3000/mcp

5. Test endpoint:

   curl -X POST http://localhost:3000/mcp \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Building

npm run build

Testing

npm test

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

GNU General Public License v3.0 - see LICENSE for details.

Copyright (C) 2025 Shayon Pal