This MCP server enables programmatic Todoist task and project management through a comprehensive tool set using the Todoist REST API v1, integrating seamlessly with MCP-compatible clients like Claude Desktop, Claude Code CLI, and Cursor IDE.
Complete Task Management: Create, read, update, delete, complete, uncomplete, and batch process tasks with support for natural language dates, priorities, labels, recurring tasks, and deadlines (distinct from due dates)
Project Organization: Full CRUD operations for projects including archiving/unarchiving, hierarchical structures, and custom view styles
Section Management: Organize tasks within projects using sections with creation, updating, deletion, and reordering capabilities
Comment System: Add, retrieve, update, and delete comments on tasks and projects with file attachment support and 15,000 character limits
Advanced Filtering: Create, retrieve, update, delete, and query custom filters using Todoist query syntax for sophisticated task searches
Flexible Reminders: Set relative (minutes before due), absolute (specific datetime), and location-based (geofenced) reminders with natural language date support
Label Management: Handle personal and shared labels with full CRUD operations, renaming, and performance-optimized caching
Batch Operations: Execute up to 100 operations per request using the Sync API for efficient bulk updates
Smart Rate Limiting: Built-in intelligent rate limiting with automatic retry using token bucket algorithms to adhere to API constraints
Completed Task Querying: Retrieve completed tasks within time-bounded windows with cursor-based pagination
Provides comprehensive task and project management capabilities through the Todoist REST API, including CRUD operations for tasks, projects, sections, comments, filters, reminders, and labels with support for natural language dates, batch operations, and file attachments.
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
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:
Any other MCP-compatible client
Installation
Option 1: Install from npm (Recommended)
Option 2: Install from source
Clone the repository:
Install dependencies:
Build the project:
Configuration
1. Set up environment variables
Edit .env
and add your Todoist API token:
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:
If installed from source:
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:
Then set your Todoist API token as an environment variable:
Or manually add the environment variable to .mcp.json
:
Scope selection:
Project scope (recommended for teams): Shared via
.mcp.json
in version controlUser 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
:
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 rootGlobal:
~/.cursor/mcp.json
in home directory
Option 1: Using environment variables
Option 2: Using environment file
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 tasksQuery 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 doneuncomplete
- Reopen completed tasksmove
- Change project/section/parent for multiple tasks
Usage Examples:
Limitations:
Maximum 50 unique tasks per operation (after deduplication)
Cannot modify
content
(task title),description
, orcomments
in bulkAll 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
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
Tools
MCP Server to create and manage tasks, projects, labels and more in Todoist, using their unified v1 API
Related MCP Servers
- AsecurityAlicenseAqualityAn MCP server that enables LLMs to interact with Todoist tasks, projects, and other features through the Todoist API.Last updated -90176MIT License
- AsecurityAlicenseAqualityComplete Todoist REST API v2 integration with support for tasks, projects, sections, comments, and labels managementLast updated -349045MIT License