A community-driven registry for Claude, Cursor, Windsurf, Cline & more. Not affiliated with Anthropic.
Are you the author? Sign in to claim
MCP server that connects Claude to Todoist for natural language task and project management with bulk operations
An MCP (Model Context Protocol) server that connects Claude with Todoist for complete task and project management through natural language.
claude mcp add todoist -e TODOIST_API_TOKEN=your_token -- npx @greirson/mcp-todoist
Add to your MCP client config (claude_desktop_config.json, ~/.claude.json, etc.):
{
"mcpServers": {
"todoist": {
"command": "npx",
"args": ["@greirson/mcp-todoist"],
"env": {
"TODOIST_API_TOKEN": "your_api_token_here"
}
}
}
}
Config locations:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.claude.jsonDry-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.
Add DRYRUN=true to your environment configuration:
{
"mcpServers": {
"todoist": {
"command": "npx",
"args": ["@greirson/mcp-todoist"],
"env": {
"TODOIST_API_TOKEN": "your_api_token_here",
"DRYRUN": "true"
}
}
}
}
[DRY-RUN] prefixesWith dry-run mode enabled, operations show what would happen:
You: "Create a task called 'Test Task' in my Work project"
Response:
[DRY-RUN] Dry-run mode enabled - mutations will be simulated
[DRY-RUN] Would create task: "Test Task" in project 2203306141, section none
Task created successfully (simulated):
ID: 100001
Title: Test Task
Project: Work (2203306141)
Priority: 4 (Normal)
All 19 MCP tools support dry-run mode:
Remove the DRYRUN environment variable or set it to false, then restart Claude Desktop to return to normal operation mode.
The server provides 19 MCP tools for complete Todoist management:
| Tool | Actions | Description |
|---|---|---|
todoist_task | create, get, update, delete, complete, reopen, quick_add | Complete task management |
todoist_task_bulk | bulk_create, bulk_update, bulk_delete, bulk_complete | Efficient multi-task operations |
todoist_subtask | create, bulk_create, convert, promote, hierarchy | Hierarchical task management |
todoist_project | create, get, update, delete, archive, collaborators | Project CRUD and sharing |
todoist_project_ops | reorder, move_to_parent, get_archived | Advanced project operations |
todoist_section | create, get, update, delete, move, reorder, archive | Section management |
todoist_label | create, get, update, delete, stats | Label management with analytics |
todoist_comment | create, get, update, delete | Task/project comments |
todoist_reminder | create, get, update, delete | Reminder management (Pro) |
todoist_filter | create, get, update, delete | Custom filters (Pro) |
todoist_collaboration | invitations, notifications, workspace operations | Team collaboration features |
todoist_user | info, productivity_stats, karma_history | User profile and stats |
todoist_utility | test_connection, test_features, test_performance, find/merge duplicates | Testing and utilities |
todoist_activity | get_log, get_events, get_summary | Activity audit trail |
todoist_task_ops | move, reorder, close | Advanced task operations |
todoist_completed | get, get_all, get_stats | Completed task retrieval |
todoist_backup | list, download | Automatic backup access |
todoist_notes | create, get, update, delete | Project notes (collaborators) |
todoist_shared_labels | create, get, rename, remove | Workspace labels (Business) |
For detailed tool documentation with parameters and examples, see TOOLS_REFERENCE.md.
"No Todoist projects found" or connection errors:
MCP server not loading:
npm list -g @greirson/mcp-todoistmcp-todoist binary: /Users/USERNAME/.npm-global/bin/mcp-todoistPermission errors:
mkdir -p ~/.config"Show me all my projects"
"Create a new project called 'Work Tasks'"
"Create a section called 'In Progress' in project 12345"
"Show me sections in the Work Tasks project"
"Create task 'Team Meeting' in project 12345"
"Add task 'Review PR' due tomorrow with labels ['Code Review', 'Urgent']"
"Create high priority task with deadline 2024-12-25"
"Update meeting task to be in section 67890"
"Mark the PR review task as complete"
# Task duration for time blocking
"Create task 'Deep work session' with 90 minute duration"
"Update task 'Meeting' to have a 2 day duration"
# Task identification by ID (more reliable than name search)
"Get task with ID 1234567890"
"Update task ID 1234567890 to priority 4"
"Complete task with ID 1234567890"
"Reopen task with ID 1234567890"
"Delete task ID 1234567890"
The Quick Add tool parses natural language text like the Todoist app, supporting multiple features in a single command:
"Quick add: Buy groceries tomorrow #Shopping @errands p1"
"Quick add: Review PR next Monday #Work @code-review p2 //Check error handling"
"Quick add: Call mom {deadline in 3 days}"
"Quick add: Team meeting today at 2pm #Work @meetings with reminder 1 hour before"
Quick Add Syntax:
#ProjectName (no spaces in project names)@label (e.g., "@urgent", "@work")+name (for shared projects)p1 (urgent), p2, p3, p4 (lowest){in 3 days} or {March 15}//your description here (must be at the end)"Create subtask 'Prepare agenda' under task 'Team Meeting'"
"Create multiple subtasks for 'Launch Project': 'Design UI', 'Write tests', 'Deploy'"
"Convert task 'Code Review' to a subtask of 'Release v2.0'"
"Promote subtask 'Bug Fix' to a main task"
"Show me the task hierarchy for 'Launch Project' with completion tracking"
"Create multiple tasks for project launch: 'Design mockups', 'Write documentation', 'Set up CI/CD'"
"Update all high priority tasks to be due next week"
"Complete all tasks containing 'review' in project 12345"
"Delete all tasks with priority 1 that are overdue"
"Add comment 'This needs urgent attention' to task 'Review PR'"
"Add comment with attachment to task 67890"
"Show all comments for task 'Team Meeting'"
"Get comments for project 12345"
"Show me all my labels"
"Create a new label called 'Urgent' with red color"
"Update the 'Work' label to be blue and mark as favorite"
"Delete the unused 'Old Project' label"
"Get usage statistics for all my labels"
"Show me all my reminders"
"Get reminders for task 'Team Meeting'"
"Create a reminder for task 'Review PR' 30 minutes before due"
"Create an absolute reminder for task 12345 at 2024-12-25T09:00:00Z"
"Update reminder 67890 to trigger at 10:00 instead"
"Delete reminder 67890"
"Show all my tasks"
"List high priority tasks due this week"
"Get tasks in project 12345"
"Test my Todoist connection"
"Run basic tests on all Todoist features" // Default: read-only API tests
"Run enhanced tests on all Todoist features" // Full CRUD testing with cleanup
"Benchmark Todoist API performance with 10 iterations"
"Validate that all MCP tools are working correctly"
When dry-run mode is enabled (DRYRUN=true), use normal commands - they'll automatically be simulated:
"Create a test task with priority 1"
"Update all overdue tasks to be due tomorrow"
"Delete all completed tasks in project 12345"
"Create 5 subtasks under task 'Project Planning'"
All these operations will validate against your real data but won't make any changes.
# Clone the repository
git clone https://github.com/greirson/mcp-todoist.git
# Navigate to directory
cd mcp-todoist
# Install dependencies
npm install
# Build the project
npm run build
# Watch for changes and rebuild
npm run watch
# Run tests
npm run test
# Run tests in watch mode
npm run test:watch
# Run tests with coverage
npm run test:coverage
# Lint code
npm run lint
# Fix linting issues
npm run lint:fix
# Format code
npm run format
# Check formatting
npm run format:check
The codebase follows a clean, modular architecture designed for maintainability and scalability:
src/index.ts: Main server entry point with request routingsrc/types.ts: TypeScript type definitions and interfacessrc/type-guards.ts: Runtime type validation functionssrc/validation.ts: Input validation and sanitizationsrc/errors.ts: Custom error types with structured handlingsrc/cache.ts: In-memory caching for performance optimizationsrc/tools/: Domain-specific MCP tool definitions organized by functionality:
task-tools.ts - Task management (9 tools)subtask-tools.ts - Subtask operations (5 tools)project-tools.ts - Project/section management (4 tools)comment-tools.ts - Comment operations (2 tools)label-tools.ts - Label management (5 tools)reminder-tools.ts - Reminder operations (4 tools)test-tools.ts - Testing and validation (3 tools)index.ts - Centralized exportssrc/handlers/: Domain-separated business logic modules:
task-handlers.ts - Task CRUD and bulk operationssubtask-handlers.ts - Hierarchical task managementproject-handlers.ts - Project and section operationscomment-handlers.ts - Comment creation and retrievallabel-handlers.ts - Label CRUD and statisticsreminder-handlers.ts - Reminder CRUD via Sync APItest-handlers.ts - API testing infrastructuretest-handlers-enhanced/ - Comprehensive CRUD testing frameworksrc/utils/: Shared utility functions:
api-helpers.ts - API response handling utilitieserror-handling.ts - Centralized error managementparameter-transformer.ts - MCP to Todoist SDK parameter format conversiondry-run-wrapper.ts - Dry-run mode implementationSee CHANGELOG.md for a detailed history of all changes.
For migration guides and breaking changes, see the full changelog.
Contributions are welcome! This project is actively maintained and I appreciate the community's interest in improving it.
I use Claude Code as part of my own development workflow -- AI-assisted coding is a normal part of how this project is built. I encourage contributors to use whatever tools make them productive, including AI coding assistants.
That said, AI tools make it very easy to generate large volumes of code that looks correct but introduces subtle issues: incorrect API mappings, performance regressions, breaking type changes, or scope creep that bundles unrelated features together. I've seen PRs that swap a URL prefix without realizing the API paths themselves changed, or that add pagination by fetching every page every time without preserving the limit parameter.
Because of this, every PR receives thorough architectural review. This isn't about gatekeeping -- it's about maintaining a codebase that hundreds of people depend on through their MCP clients. PRs that appear to be unreviewed AI output will receive detailed feedback on what needs to change and why, so you can learn and resubmit.
Before submitting a pull request, please ensure:
One concern per PR. A bug fix is one PR. A new feature is another. A documentation update is another. If your diff touches 40+ files across unrelated features, it needs to be split. Mixed-scope PRs will be sent back for splitting.
You understand what your code does. If an AI tool wrote it, read it critically before submitting. Can you explain why each change is necessary? Could you debug it if it broke? If not, it's not ready.
Tests are included or updated. New features need tests. Bug fixes need a test that would have caught the bug. If you're changing API endpoints, verify they work against the live API -- don't just trust that a URL swap is sufficient.
Manual verification is done. Run npm run build and npm test locally. If you're changing API integration code, test against your own Todoist account (dry-run mode is available with DRYRUN=true). Include evidence of verification in your PR description.
CI must pass. PRs with failing CI checks will not be reviewed until they're green.
mainnpm run build && npm test && npm run lint to verifyIf you're unsure whether a change is wanted or how to approach it, open an issue first to discuss. This saves everyone time and helps align on the right approach before code is written.
This project is licensed under the MIT License - see the LICENSE file for details.
If you encounter any issues or need support, please file an issue on the GitHub repository.
A Jetbrains IDE IntelliJ plugin aimed to provide coding agents the ability to leverage intelliJ's indexing of the codeba
Run Claude Code as an MCP server so any agent can delegate coding tasks to it
@microsoft✓ OfficialBrowser automation using accessibility snapshots instead of screenshots