Skip to main content
Glama

mcp-todoist

Todoist MCP Server

npm version License: GPL-3.0 Node.js 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

Add to Cursor

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 CONTRIBUTING.md for guidelines.

License

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

Copyright (C) 2025 Shayon Pal

Related MCP Servers

  • A
    security
    A
    license
    A
    quality
    An MCP server that enables LLMs to interact with Todoist tasks, projects, and other features through the Todoist API.
    Last updated -
    90
    176
    MIT License
    • Apple
    • Linux
  • A
    security
    A
    license
    A
    quality
    Complete Todoist REST API v2 integration with support for tasks, projects, sections, comments, and labels management
    Last updated -
    34
    90
    45
    MIT License

View all related MCP servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/shayonpal/mcp-todoist'

If you have feedback or need assistance with the MCP directory API, please join our Discord server