mcp-todoist

# Todoist MCP Server [](https://www.npmjs.com/package/@shayonpal/mcp-todoist) [](LICENSE) [](package.json) <a href="https://glama.ai/mcp/servers/@shayonpal/mcp-todoist"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@shayonpal/mcp-todoist/badge" /> </a> 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](#features) - [Prerequisites](#prerequisites) - [Installation](#installation) - [Configuration](#configuration) - [Available Tools](#available-tools) - [Rate Limiting](#rate-limiting) - [Development](#development) - [Contributing](#contributing) - [License](#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](https://todoist.com)) - **Todoist API token** ([Get yours here](https://todoist.com/help/articles/find-your-api-token)) - Any of the popular **MCP clients**, such as: - [Claude Desktop](https://claude.ai/download) - [Claude Code CLI](https://github.com/anthropics/claude-code) - [Codex CLI](https://github.com/openai/codex) - [Cursor IDE or CLI](https://cursor.com/) - [Raycast MCP Extension](https://www.raycast.com/) - Any other MCP-compatible client ## Installation ### Option 1: Install from npm (Recommended) ```bash npm i @shayonpal/mcp-todoist ``` ### Option 2: Install from source 1. Clone the repository: ```bash git clone https://github.com/shayonpal/mcp-todoist.git cd mcp-todoist ``` 2. Install dependencies: ```bash npm install ``` 3. Build the project: ```bash npm run build ``` ## Configuration ### 1. Set up environment variables ```bash cp .env.example .env ``` Edit `.env` and add your Todoist API token: ```bash 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:** ```json { "mcpServers": { "todoist": { "command": "npx", "args": ["-y", "@shayonpal/mcp-todoist"], "env": { "TODOIST_API_TOKEN": "your_api_token_here" } } } } ``` **If installed from source:** ```json { "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: ```bash # 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: ```bash export TODOIST_API_TOKEN=your_api_token_here ``` Or manually add the environment variable to `.mcp.json`: ```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`: ```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** [](cursor://anysphere.cursor-deeplink/mcp/install?name=todoist&config=eyJ0b2RvaXN0Ijp7InR5cGUiOiJzdGRpbyIsImNvbW1hbmQiOiJucHgiLCJhcmdzIjpbIi15IiwiQHNoYXlvbnBhbC9tY3AtdG9kb2lzdCJdLCJlbnYiOnsiVE9ET0lTVF9BUElfVE9LRU4iOiIke2VudjpUT0RPSVNUX0FQSV9UT0tFTn0ifX19) 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** ```json { "mcpServers": { "todoist": { "type": "stdio", "command": "npx", "args": ["-y", "@shayonpal/mcp-todoist"], "env": { "TODOIST_API_TOKEN": "${env:TODOIST_API_TOKEN}" } } } } ``` **Option 2: Using environment file** ```json { "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 ```json { "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**: ```json // 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 ```bash # 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](CONTRIBUTING.md) for guidelines. ## License GNU General Public License v3.0 - see [LICENSE](LICENSE) for details. Copyright (C) 2025 Shayon Pal