mcp-todoist

shayonpal/mcp-todoist

3.3

If you are the rightful owner of mcp-todoist and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Todoist MCP Server is a tool that allows for programmatic management of Todoist tasks and projects using the Todoist REST API v1.

Tools
6
Resources
0
Prompts
0

Todoist MCP Server

npm version

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

  • 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

Installation

Option 1: Install from npm (Recommended)

npm i @shayonpal/mcp-todoist

Option 2: Install from source

  1. Clone the repository:
git clone https://github.com/shayonpal/mcp-todoist.git
cd mcp-todoist
  1. Install dependencies:
npm install
  1. Build the project:
npm run build

Configuration

1. Set up environment variables

cp .env.example .env

Edit .env and add your Todoist API token:

TODOIST_API_TOKEN=your_todoist_api_token_here

2. Configure your MCP client

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

If installed from npm:

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

If installed from source:

{
  "mcpServers": {
    "todoist": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-todoist/dist/index.js"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Note: When using source installation, use absolute paths in the configuration.

Claude Code CLI

Recommended: Use CLI command

Add the server using the claude mcp add command:

# Project scope (shared with team, stored in .mcp.json)
claude mcp add todoist --scope project npx -y @shayonpal/mcp-todoist

# User scope (personal, works across all projects)
claude mcp add todoist --scope user npx -y @shayonpal/mcp-todoist

# Local scope (personal, current project only) - default
claude mcp add todoist npx -y @shayonpal/mcp-todoist

Then set your Todoist API token as an environment variable:

export TODOIST_API_TOKEN=your_api_token_here

Or manually add the environment variable to .mcp.json:

{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["-y", "@shayonpal/mcp-todoist"],
      "env": {
        "TODOIST_API_TOKEN": "${TODOIST_API_TOKEN}"
      }
    }
  }
}

Scope selection:

  • Project scope (recommended for teams): Shared via .mcp.json in version control
  • User scope: Personal, available across all projects on your machine
  • Local scope: Personal, specific to current project only (default)
Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.todoist]
command = "npx"
args = ["-y", "@shayonpal/mcp-todoist"]
env = { "TODOIST_API_TOKEN" = "your_api_token_here" }
startup_timeout_ms = 20000

Note: Codex uses TOML format with mcp_servers (underscore). All strings must be quoted.

Cursor IDE

Recommended: One-click install

Click the button above to automatically install the server in Cursor. Make sure you have TODOIST_API_TOKEN set as an environment variable.

Manual installation:

Configuration locations:

  • Project-specific: .cursor/mcp.json in project root
  • Global: ~/.cursor/mcp.json in home directory

Option 1: Using environment variables

{
  "mcpServers": {
    "todoist": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@shayonpal/mcp-todoist"],
      "env": {
        "TODOIST_API_TOKEN": "${env:TODOIST_API_TOKEN}"
      }
    }
  }
}

Option 2: Using environment file

{
  "mcpServers": {
    "todoist": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@shayonpal/mcp-todoist"],
      "envFile": ".env"
    }
  }
}

Supported config interpolation:

  • ${env:NAME} - Environment variables
  • ${userHome} - Path to home folder
  • ${workspaceFolder} - Project root directory
  • ${workspaceFolderBasename} - Project name
Other MCP Clients

Refer to your MCP client's documentation for configuration instructions. The server uses STDIO transport and follows MCP protocol version 2024-11-05.

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

# Run in development mode with hot reload
npm run dev

# Build TypeScript
npm run build

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate test coverage report
npm run test:coverage

# Lint code
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format code with Prettier
npm run format

# Type-check without emitting
npm run typecheck

Contributing

Contributions are welcome! Please see for guidelines.

License

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

Copyright (C) 2025 Shayon Pal