An MCP (Model Context Protocol) server that connects Claude with Todoist for complete task and project management through natural language. 1. Download todoist-mcp.mcpb from the latest release 2. Double-click the file (or drag onto Claude Desktop) 3. Enter your Todoist API token when prompted 4. Start chatting: "Show me my Todoist projects" Manual JSON configuration Add to your MCP client config (
Add this skill
npx mdskills install greirson/mcp-todoistComprehensive Todoist MCP server with 19 tools, excellent setup docs, and dry-run mode
1# Todoist MCP Server23An MCP (Model Context Protocol) server that connects Claude with Todoist for complete task and project management through natural language.45## Installation67### Claude Desktop (One-Click Install)891. Download **[todoist-mcp.mcpb](https://github.com/greirson/mcp-todoist/releases/latest)** from the latest release102. Double-click the file (or drag onto Claude Desktop)113. Enter your [Todoist API token](https://todoist.com/app/settings/integrations/developer) when prompted124. Start chatting: _"Show me my Todoist projects"_1314### Claude Code / Other MCP Clients1516```bash17claude mcp add todoist -e TODOIST_API_TOKEN=your_token -- npx @greirson/mcp-todoist18```1920<details>21<summary>Manual JSON configuration</summary>2223Add to your MCP client config (`claude_desktop_config.json`, `~/.claude.json`, etc.):2425```json26{27 "mcpServers": {28 "todoist": {29 "command": "npx",30 "args": ["@greirson/mcp-todoist"],31 "env": {32 "TODOIST_API_TOKEN": "your_api_token_here"33 }34 }35 }36}37```3839**Config locations:**4041- Claude Desktop (macOS): `~/Library/Application Support/Claude/claude_desktop_config.json`42- Claude Desktop (Windows): `%APPDATA%\Claude\claude_desktop_config.json`43- Claude Code: `~/.claude.json`4445</details>4647## Features4849- **19 MCP Tools** for complete Todoist management50- **Task Management**: Create, update, delete, complete, reopen tasks with priorities, due dates, labels51- **Bulk Operations**: Process multiple tasks efficiently52- **Subtasks**: Hierarchical task management with completion tracking53- **Projects & Sections**: Full organization support54- **Labels, Filters, Reminders**: Pro/Business features supported55- **Natural Language**: Quick add with Todoist's natural language parsing56- **Dry-Run Mode**: Test operations without making changes5758## Dry-Run Mode5960Dry-run mode allows you to test operations and automations without making any real changes to your Todoist workspace. This is perfect for testing, debugging, learning the API, or validating automation scripts before running them for real.6162### How to Enable Dry-Run Mode6364Add `DRYRUN=true` to your environment configuration:6566```json67{68 "mcpServers": {69 "todoist": {70 "command": "npx",71 "args": ["@greirson/mcp-todoist"],72 "env": {73 "TODOIST_API_TOKEN": "your_api_token_here",74 "DRYRUN": "true"75 }76 }77 }78}79```8081### What Dry-Run Mode Does8283- **Validates Operations**: Uses real API data to validate that operations would succeed84- **Simulates Mutations**: Create, update, delete, and complete operations are simulated (not executed)85- **Real Data Queries**: Read operations (get tasks, projects, labels) use the real API86- **Detailed Logging**: Shows exactly what would happen with clear `[DRY-RUN]` prefixes87- **Error Detection**: Catches the same errors that would occur in real execution8889### Use Cases9091- **Testing Automations**: Validate complex bulk operations before executing92- **Learning the API**: Explore functionality without fear of making unwanted changes93- **Debugging Issues**: Understand what operations would be performed94- **Safe Experimentation**: Try new workflows without affecting your actual tasks95- **Training and Demos**: Show how operations work without modifying real data9697### Example Usage9899With dry-run mode enabled, operations show what would happen:100101```102You: "Create a task called 'Test Task' in my Work project"103104Response:105[DRY-RUN] Dry-run mode enabled - mutations will be simulated106[DRY-RUN] Would create task: "Test Task" in project 2203306141, section none107108Task created successfully (simulated):109ID: 100001110Title: Test Task111Project: Work (2203306141)112Priority: 4 (Normal)113```114115### Supported Operations116117All 19 MCP tools support dry-run mode:118119- Task creation, updates, completion, and deletion120- Subtask operations and hierarchy changes121- Bulk operations across multiple tasks122- Project and section creation123- Label management operations124- Reminder CRUD operations125- Comment creation126127### Disabling Dry-Run Mode128129Remove the `DRYRUN` environment variable or set it to `false`, then restart Claude Desktop to return to normal operation mode.130131## Tools Overview132133The server provides **19 MCP tools** for complete Todoist management:134135| Tool | Actions | Description |136| ----------------------- | ----------------------------------------------------------------------- | ------------------------------- |137| `todoist_task` | create, get, update, delete, complete, reopen, quick_add | Complete task management |138| `todoist_task_bulk` | bulk_create, bulk_update, bulk_delete, bulk_complete | Efficient multi-task operations |139| `todoist_subtask` | create, bulk_create, convert, promote, hierarchy | Hierarchical task management |140| `todoist_project` | create, get, update, delete, archive, collaborators | Project CRUD and sharing |141| `todoist_project_ops` | reorder, move_to_parent, get_archived | Advanced project operations |142| `todoist_section` | create, get, update, delete, move, reorder, archive | Section management |143| `todoist_label` | create, get, update, delete, stats | Label management with analytics |144| `todoist_comment` | create, get, update, delete | Task/project comments |145| `todoist_reminder` | create, get, update, delete | Reminder management (Pro) |146| `todoist_filter` | create, get, update, delete | Custom filters (Pro) |147| `todoist_collaboration` | invitations, notifications, workspace operations | Team collaboration features |148| `todoist_user` | info, productivity_stats, karma_history | User profile and stats |149| `todoist_utility` | test_connection, test_features, test_performance, find/merge duplicates | Testing and utilities |150| `todoist_activity` | get_log, get_events, get_summary | Activity audit trail |151| `todoist_task_ops` | move, reorder, close | Advanced task operations |152| `todoist_completed` | get, get_all, get_stats | Completed task retrieval |153| `todoist_backup` | list, download | Automatic backup access |154| `todoist_notes` | create, get, update, delete | Project notes (collaborators) |155| `todoist_shared_labels` | create, get, rename, remove | Workspace labels (Business) |156157For detailed tool documentation with parameters and examples, see **[TOOLS_REFERENCE.md](TOOLS_REFERENCE.md)**.158159## Troubleshooting160161### Common Issues162163**"No Todoist projects found" or connection errors:**164165- Verify your API token is correct166- Check that the token is properly set in your claude_desktop_config.json167- Ensure there are no extra spaces or quotes around your token168169**MCP server not loading:**170171- Confirm the package is installed globally: `npm list -g @greirson/mcp-todoist`172- Restart Claude Desktop completely173- Check the configuration file path is correct for your operating system174- Try the full path to the `mcp-todoist` binary: `/Users/USERNAME/.npm-global/bin/mcp-todoist`175176**Permission errors:**177178- On macOS/Linux, you may need to create the config directory: `mkdir -p ~/.config`179- Ensure Claude Desktop has permission to read the config file180181## Usage Examples182183### Project & Section Setup184185```186"Show me all my projects"187"Create a new project called 'Work Tasks'"188"Create a section called 'In Progress' in project 12345"189"Show me sections in the Work Tasks project"190```191192### Task Creation & Management193194```195"Create task 'Team Meeting' in project 12345"196"Add task 'Review PR' due tomorrow with labels ['Code Review', 'Urgent']"197"Create high priority task with deadline 2024-12-25"198"Update meeting task to be in section 67890"199"Mark the PR review task as complete"200201# Task duration for time blocking202"Create task 'Deep work session' with 90 minute duration"203"Update task 'Meeting' to have a 2 day duration"204205# Task identification by ID (more reliable than name search)206"Get task with ID 1234567890"207"Update task ID 1234567890 to priority 4"208"Complete task with ID 1234567890"209"Reopen task with ID 1234567890"210"Delete task ID 1234567890"211```212213### Quick Add214215The Quick Add tool parses natural language text like the Todoist app, supporting multiple features in a single command:216217```218"Quick add: Buy groceries tomorrow #Shopping @errands p1"219"Quick add: Review PR next Monday #Work @code-review p2 //Check error handling"220"Quick add: Call mom {deadline in 3 days}"221"Quick add: Team meeting today at 2pm #Work @meetings with reminder 1 hour before"222```223224**Quick Add Syntax:**225226- **Due dates**: Natural language dates like "tomorrow", "next Friday", "Jan 23", "in 3 days"227- **Projects**: `#ProjectName` (no spaces in project names)228- **Labels**: `@label` (e.g., "@urgent", "@work")229- **Assignees**: `+name` (for shared projects)230- **Priority**: `p1` (urgent), `p2`, `p3`, `p4` (lowest)231- **Deadlines**: `{in 3 days}` or `{March 15}`232- **Descriptions**: `//your description here` (must be at the end)233234### Subtask Management235236```237"Create subtask 'Prepare agenda' under task 'Team Meeting'"238"Create multiple subtasks for 'Launch Project': 'Design UI', 'Write tests', 'Deploy'"239"Convert task 'Code Review' to a subtask of 'Release v2.0'"240"Promote subtask 'Bug Fix' to a main task"241"Show me the task hierarchy for 'Launch Project' with completion tracking"242```243244### Bulk Operations245246```247"Create multiple tasks for project launch: 'Design mockups', 'Write documentation', 'Set up CI/CD'"248"Update all high priority tasks to be due next week"249"Complete all tasks containing 'review' in project 12345"250"Delete all tasks with priority 1 that are overdue"251```252253### Comment Management254255```256"Add comment 'This needs urgent attention' to task 'Review PR'"257"Add comment with attachment to task 67890"258"Show all comments for task 'Team Meeting'"259"Get comments for project 12345"260```261262### Label Management263264```265"Show me all my labels"266"Create a new label called 'Urgent' with red color"267"Update the 'Work' label to be blue and mark as favorite"268"Delete the unused 'Old Project' label"269"Get usage statistics for all my labels"270```271272### Reminder Management (Pro/Business)273274```275"Show me all my reminders"276"Get reminders for task 'Team Meeting'"277"Create a reminder for task 'Review PR' 30 minutes before due"278"Create an absolute reminder for task 12345 at 2024-12-25T09:00:00Z"279"Update reminder 67890 to trigger at 10:00 instead"280"Delete reminder 67890"281```282283### Task Discovery284285```286"Show all my tasks"287"List high priority tasks due this week"288"Get tasks in project 12345"289```290291### Testing & Validation292293```294"Test my Todoist connection"295"Run basic tests on all Todoist features" // Default: read-only API tests296"Run enhanced tests on all Todoist features" // Full CRUD testing with cleanup297"Benchmark Todoist API performance with 10 iterations"298"Validate that all MCP tools are working correctly"299```300301### Dry-Run Testing302303When dry-run mode is enabled (DRYRUN=true), use normal commands - they'll automatically be simulated:304305```306"Create a test task with priority 1"307"Update all overdue tasks to be due tomorrow"308"Delete all completed tasks in project 12345"309"Create 5 subtasks under task 'Project Planning'"310```311312All these operations will validate against your real data but won't make any changes.313314## Development315316### Building from source317318```bash319# Clone the repository320git clone https://github.com/greirson/mcp-todoist.git321322# Navigate to directory323cd mcp-todoist324325# Install dependencies326npm install327328# Build the project329npm run build330```331332### Development Commands333334```bash335# Watch for changes and rebuild336npm run watch337338# Run tests339npm run test340341# Run tests in watch mode342npm run test:watch343344# Run tests with coverage345npm run test:coverage346347# Lint code348npm run lint349350# Fix linting issues351npm run lint:fix352353# Format code354npm run format355356# Check formatting357npm run format:check358```359360### Architecture361362The codebase follows a clean, modular architecture designed for maintainability and scalability:363364#### Core Structure365366- **`src/index.ts`**: Main server entry point with request routing367- **`src/types.ts`**: TypeScript type definitions and interfaces368- **`src/type-guards.ts`**: Runtime type validation functions369- **`src/validation.ts`**: Input validation and sanitization370- **`src/errors.ts`**: Custom error types with structured handling371- **`src/cache.ts`**: In-memory caching for performance optimization372373#### Modular Tool Organization374375- **`src/tools/`**: Domain-specific MCP tool definitions organized by functionality:376 - `task-tools.ts` - Task management (9 tools)377 - `subtask-tools.ts` - Subtask operations (5 tools)378 - `project-tools.ts` - Project/section management (4 tools)379 - `comment-tools.ts` - Comment operations (2 tools)380 - `label-tools.ts` - Label management (5 tools)381 - `reminder-tools.ts` - Reminder operations (4 tools)382 - `test-tools.ts` - Testing and validation (3 tools)383 - `index.ts` - Centralized exports384385#### Business Logic Handlers386387- **`src/handlers/`**: Domain-separated business logic modules:388 - `task-handlers.ts` - Task CRUD and bulk operations389 - `subtask-handlers.ts` - Hierarchical task management390 - `project-handlers.ts` - Project and section operations391 - `comment-handlers.ts` - Comment creation and retrieval392 - `label-handlers.ts` - Label CRUD and statistics393 - `reminder-handlers.ts` - Reminder CRUD via Sync API394 - `test-handlers.ts` - API testing infrastructure395 - `test-handlers-enhanced/` - Comprehensive CRUD testing framework396397#### Utility Modules398399- **`src/utils/`**: Shared utility functions:400 - `api-helpers.ts` - API response handling utilities401 - `error-handling.ts` - Centralized error management402 - `parameter-transformer.ts` - MCP to Todoist SDK parameter format conversion403 - `dry-run-wrapper.ts` - Dry-run mode implementation404405## Changelog406407See [CHANGELOG.md](CHANGELOG.md) for a detailed history of all changes.408409For migration guides and breaking changes, see the full changelog.410411## Contributing412413Contributions are welcome! Feel free to submit a Pull Request.414415## License416417This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.418419## Issues and Support420421If you encounter any issues or need support, please file an issue on the [GitHub repository](https://github.com/greirson/mcp-todoist/issues).422
Full transparency — inspect the skill content before installing.