mcp-todoist by shayonpal - MCP Server

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.

Features
Prerequisites
Installation
Configuration
Available Tools
Rate Limiting
Development
Contributing
License

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:

Fork this repository
Deploy to Vercel (button below)
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

Clone the repository:

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

Install dependencies:
```
npm install
```

Create .env.local:

echo "TODOIST_API_TOKEN=your_token_here" > .env.local

Start development server:
```
vercel dev
```
Server runs at http://localhost:3000/mcp

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

License

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

shayonpal/mcp-todoist

Todoist MCP Server

Table of Contents

Features

Prerequisites

Installation

For Deployment

Configuration

MCP Clients

Claude Desktop / Claude Code

Available Tools

todoist_tasks

todoist_projects

todoist_sections

todoist_comments

todoist_filters

todoist_reminders

todoist_labels

todoist_bulk_tasks

Rate Limiting

Development

Prerequisites

Local Setup

Building

Testing

Contributing

License