Skip to content
Back to search

mcp-todoist

MCP server that connects Claude to Todoist for natural language task and project management with bulk operations

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/greirson--mcp-todoist/badge.svg)](/listings/greirson--mcp-todoist)

HTML

<a href="/listings/greirson--mcp-todoist"><img src="/api/listings/greirson--mcp-todoist/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Desktop (One-Click Install)

1. Download **[todoist-mcp.mcpb](https://github.com/greirson/mcp-todoist/releases/latest)** from the latest release 2. Double-click the file (or drag onto Claude Desktop) 3. Enter your [Todoist API token](https://todoist.com/app/settings/integrations/developer) when prompted 4. Start chatting: _"Show me my Todoist projects"_

Claude Code / Other MCP Clients

claude mcp add todoist -e TODOIST_API_TOKEN=your_token -- npx @greirson/mcp-todoist

<details> <summary>Manual JSON configuration</summary>

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:**

- Claude Desktop (macOS): `~/Library/Application Support/Claude/claude_desktop_config.json` - Claude Desktop (Windows): `%APPDATA%\Claude\claude_desktop_config.json` - Claude Code: `~/.claude.json`

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 461 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Todoist MCP Server
  2. An MCP (Model Context Protocol) server that connects Claude with Todoist for complete task and project management through natural language.
  3. ## Installation
  4. ### Claude Desktop (One-Click Install)
  5. 1. Download **[todoist-mcp.mcpb](https://github.com/greirson/mcp-todoist/releases/latest)** from the latest release
  6. 2. Double-click the file (or drag onto Claude Desktop)
  7. 3. Enter your [Todoist API token](https://todoist.com/app/settings/integrations/developer) when prompted
  8. 4. Start chatting: _"Show me my Todoist projects"_
  9. ### Claude Code / Other MCP Clients
  10. ```bash
  11. claude mcp add todoist -e TODOIST_API_TOKEN=your_token -- npx @greirson/mcp-todoist
  12. ```
  13. <details>
  14. <summary>Manual JSON configuration</summary>
  15. Add to your MCP client config (`claude_desktop_config.json`, `~/.claude.json`, etc.):
  16. ```json
  17. {
  18. "mcpServers": {
  19. "todoist": {
  20. "command": "npx",
  21. "args": ["@greirson/mcp-todoist"],
  22. "env": {
  23. "TODOIST_API_TOKEN": "your_api_token_here"
  24. }
  25. }
  26. }
  27. }
  28. ```
  29. **Config locations:**
  30. - Claude Desktop (macOS): `~/Library/Application Support/Claude/claude_desktop_config.json`
  31. - Claude Desktop (Windows): `%APPDATA%\Claude\claude_desktop_config.json`
  32. - Claude Code: `~/.claude.json`
  33. </details>
  34. ## Features
  35. - **19 MCP Tools** for complete Todoist management
  36. - **Task Management**: Create, update, delete, complete, reopen tasks with priorities, due dates, labels
  37. - **Bulk Operations**: Process multiple tasks efficiently
  38. - **Subtasks**: Hierarchical task management with completion tracking
  39. - **Projects & Sections**: Full organization support
  40. - **Labels, Filters, Reminders**: Pro/Business features supported
  41. - **Natural Language**: Quick add with Todoist's natural language parsing
  42. - **Dry-Run Mode**: Test operations without making changes
  43. ## Dry-Run Mode
  44. Dry-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.
  45. ### How to Enable Dry-Run Mode
  46. Add `DRYRUN=true` to your environment configuration:
  47. ```json
  48. {
  49. "mcpServers": {
  50. "todoist": {
  51. "command": "npx",
  52. "args": ["@greirson/mcp-todoist"],
  53. "env": {
  54. "TODOIST_API_TOKEN": "your_api_token_here",
  55. "DRYRUN": "true"
  56. }
  57. }
  58. }
  59. }
  60. ```
  61. ### What Dry-Run Mode Does
  62. - **Validates Operations**: Uses real API data to validate that operations would succeed
  63. - **Simulates Mutations**: Create, update, delete, and complete operations are simulated (not executed)
  64. - **Real Data Queries**: Read operations (get tasks, projects, labels) use the real API
  65. - **Detailed Logging**: Shows exactly what would happen with clear `[DRY-RUN]` prefixes
  66. - **Error Detection**: Catches the same errors that would occur in real execution
  67. ### Use Cases
  68. - **Testing Automations**: Validate complex bulk operations before executing
  69. - **Learning the API**: Explore functionality without fear of making unwanted changes
  70. - **Debugging Issues**: Understand what operations would be performed
  71. - **Safe Experimentation**: Try new workflows without affecting your actual tasks
  72. - **Training and Demos**: Show how operations work without modifying real data
  73. ### Example Usage
  74. With dry-run mode enabled, operations show what would happen:
  75. ```
  76. You: "Create a task called 'Test Task' in my Work project"
  77. Response:
  78. [DRY-RUN] Dry-run mode enabled - mutations will be simulated
  79. [DRY-RUN] Would create task: "Test Task" in project 2203306141, section none
  80. Task created successfully (simulated):
  81. ID: 100001
  82. Title: Test Task
  83. Project: Work (2203306141)
  84. Priority: 4 (Normal)
  85. ```
  86. ### Supported Operations
  87. All 19 MCP tools support dry-run mode:
  88. - Task creation, updates, completion, and deletion
  89. - Subtask operations and hierarchy changes
  90. - Bulk operations across multiple tasks
  91. - Project and section creation
  92. - Label management operations
  93. - Reminder CRUD operations
  94. - Comment creation
  95. ### Disabling Dry-Run Mode
  96. Remove the `DRYRUN` environment variable or set it to `false`, then restart Claude Desktop to return to normal operation mode.
  97. ## Tools Overview
  98. The server provides **19 MCP tools** for complete Todoist management:
  99. | Tool | Actions | Description |
  100. | ----------------------- | ----------------------------------------------------------------------- | ------------------------------- |
  101. | `todoist_task` | create, get, update, delete, complete, reopen, quick_add | Complete task management |
  102. | `todoist_task_bulk` | bulk_create, bulk_update, bulk_delete, bulk_complete | Efficient multi-task operations |
  103. | `todoist_subtask` | create, bulk_create, convert, promote, hierarchy | Hierarchical task management |
  104. | `todoist_project` | create, get, update, delete, archive, collaborators | Project CRUD and sharing |
  105. | `todoist_project_ops` | reorder, move_to_parent, get_archived | Advanced project operations |
  106. | `todoist_section` | create, get, update, delete, move, reorder, archive | Section management |
  107. | `todoist_label` | create, get, update, delete, stats | Label management with analytics |
  108. | `todoist_comment` | create, get, update, delete | Task/project comments |
  109. | `todoist_reminder` | create, get, update, delete | Reminder management (Pro) |
  110. | `todoist_filter` | create, get, update, delete | Custom filters (Pro) |
  111. | `todoist_collaboration` | invitations, notifications, workspace operations | Team collaboration features |
  112. | `todoist_user` | info, productivity_stats, karma_history | User profile and stats |
  113. | `todoist_utility` | test_connection, test_features, test_performance, find/merge duplicates | Testing and utilities |
  114. | `todoist_activity` | get_log, get_events, get_summary | Activity audit trail |
  115. | `todoist_task_ops` | move, reorder, close | Advanced task operations |
  116. | `todoist_completed` | get, get_all, get_stats | Completed task retrieval |
  117. | `todoist_backup` | list, download | Automatic backup access |
  118. | `todoist_notes` | create, get, update, delete | Project notes (collaborators) |
  119. | `todoist_shared_labels` | create, get, rename, remove | Workspace labels (Business) |
  120. For detailed tool documentation with parameters and examples, see **[TOOLS_REFERENCE.md](TOOLS_REFERENCE.md)**.
  121. ## Troubleshooting
  122. ### Common Issues
  123. **"No Todoist projects found" or connection errors:**
  124. - Verify your API token is correct
  125. - Check that the token is properly set in your claude_desktop_config.json
  126. - Ensure there are no extra spaces or quotes around your token
  127. **MCP server not loading:**
  128. - Confirm the package is installed globally: `npm list -g @greirson/mcp-todoist`
  129. - Restart Claude Desktop completely
  130. - Check the configuration file path is correct for your operating system
  131. - Try the full path to the `mcp-todoist` binary: `/Users/USERNAME/.npm-global/bin/mcp-todoist`
  132. **Permission errors:**
  133. - On macOS/Linux, you may need to create the config directory: `mkdir -p ~/.config`
  134. - Ensure Claude Desktop has permission to read the config file
  135. ## Usage Examples
  136. ### Project & Section Setup
  137. ```
  138. "Show me all my projects"
  139. "Create a new project called 'Work Tasks'"
  140. "Create a section called 'In Progress' in project 12345"
  141. "Show me sections in the Work Tasks project"
  142. ```
  143. ### Task Creation & Management
  144. ```
  145. "Create task 'Team Meeting' in project 12345"
  146. "Add task 'Review PR' due tomorrow with labels ['Code Review', 'Urgent']"
  147. "Create high priority task with deadline 2024-12-25"
  148. "Update meeting task to be in section 67890"
  149. "Mark the PR review task as complete"
  150. # Task duration for time blocking
  151. "Create task 'Deep work session' with 90 minute duration"
  152. "Update task 'Meeting' to have a 2 day duration"
  153. # Task identification by ID (more reliable than name search)
  154. "Get task with ID 1234567890"
  155. "Update task ID 1234567890 to priority 4"
  156. "Complete task with ID 1234567890"
  157. "Reopen task with ID 1234567890"
  158. "Delete task ID 1234567890"
  159. ```
  160. ### Quick Add
  161. The Quick Add tool parses natural language text like the Todoist app, supporting multiple features in a single command:
  162. ```
  163. "Quick add: Buy groceries tomorrow #Shopping @errands p1"
  164. "Quick add: Review PR next Monday #Work @code-review p2 //Check error handling"
  165. "Quick add: Call mom {deadline in 3 days}"
  166. "Quick add: Team meeting today at 2pm #Work @meetings with reminder 1 hour before"
  167. ```
  168. **Quick Add Syntax:**
  169. - **Due dates**: Natural language dates like "tomorrow", "next Friday", "Jan 23", "in 3 days"
  170. - **Projects**: `#ProjectName` (no spaces in project names)
  171. - **Labels**: `@label` (e.g., "@urgent", "@work")
  172. - **Assignees**: `+name` (for shared projects)
  173. - **Priority**: `p1` (urgent), `p2`, `p3`, `p4` (lowest)
  174. - **Deadlines**: `{in 3 days}` or `{March 15}`
  175. - **Descriptions**: `//your description here` (must be at the end)
  176. ### Subtask Management
  177. ```
  178. "Create subtask 'Prepare agenda' under task 'Team Meeting'"
  179. "Create multiple subtasks for 'Launch Project': 'Design UI', 'Write tests', 'Deploy'"
  180. "Convert task 'Code Review' to a subtask of 'Release v2.0'"
  181. "Promote subtask 'Bug Fix' to a main task"
  182. "Show me the task hierarchy for 'Launch Project' with completion tracking"
  183. ```
  184. ### Bulk Operations
  185. ```
  186. "Create multiple tasks for project launch: 'Design mockups', 'Write documentation', 'Set up CI/CD'"
  187. "Update all high priority tasks to be due next week"
  188. "Complete all tasks containing 'review' in project 12345"
  189. "Delete all tasks with priority 1 that are overdue"
  190. ```
  191. ### Comment Management
  192. ```
  193. "Add comment 'This needs urgent attention' to task 'Review PR'"
  194. "Add comment with attachment to task 67890"
  195. "Show all comments for task 'Team Meeting'"
  196. "Get comments for project 12345"
  197. ```
  198. ### Label Management
  199. ```
  200. "Show me all my labels"
  201. "Create a new label called 'Urgent' with red color"
  202. "Update the 'Work' label to be blue and mark as favorite"
  203. "Delete the unused 'Old Project' label"
  204. "Get usage statistics for all my labels"
  205. ```
  206. ### Reminder Management (Pro/Business)
  207. ```
  208. "Show me all my reminders"
  209. "Get reminders for task 'Team Meeting'"
  210. "Create a reminder for task 'Review PR' 30 minutes before due"
  211. "Create an absolute reminder for task 12345 at 2024-12-25T09:00:00Z"
  212. "Update reminder 67890 to trigger at 10:00 instead"
  213. "Delete reminder 67890"
  214. ```
  215. ### Task Discovery
  216. ```
  217. "Show all my tasks"
  218. "List high priority tasks due this week"
  219. "Get tasks in project 12345"
  220. ```
  221. ### Testing & Validation
  222. ```
  223. "Test my Todoist connection"
  224. "Run basic tests on all Todoist features" // Default: read-only API tests
  225. "Run enhanced tests on all Todoist features" // Full CRUD testing with cleanup
  226. "Benchmark Todoist API performance with 10 iterations"
  227. "Validate that all MCP tools are working correctly"
  228. ```
  229. ### Dry-Run Testing
  230. When dry-run mode is enabled (DRYRUN=true), use normal commands - they'll automatically be simulated:
  231. ```
  232. "Create a test task with priority 1"
  233. "Update all overdue tasks to be due tomorrow"
  234. "Delete all completed tasks in project 12345"
  235. "Create 5 subtasks under task 'Project Planning'"
  236. ```
  237. All these operations will validate against your real data but won't make any changes.
  238. ## Development
  239. ### Building from source
  240. ```bash
  241. # Clone the repository
  242. git clone https://github.com/greirson/mcp-todoist.git
  243. # Navigate to directory
  244. cd mcp-todoist
  245. # Install dependencies
  246. npm install
  247. # Build the project
  248. npm run build
  249. ```
  250. ### Development Commands
  251. ```bash
  252. # Watch for changes and rebuild
  253. npm run watch
  254. # Run tests
  255. npm run test
  256. # Run tests in watch mode
  257. npm run test:watch
  258. # Run tests with coverage
  259. npm run test:coverage
  260. # Lint code
  261. npm run lint
  262. # Fix linting issues
  263. npm run lint:fix
  264. # Format code
  265. npm run format
  266. # Check formatting
  267. npm run format:check
  268. ```
  269. ### Architecture
  270. The codebase follows a clean, modular architecture designed for maintainability and scalability:
  271. #### Core Structure
  272. - **`src/index.ts`**: Main server entry point with request routing
  273. - **`src/types.ts`**: TypeScript type definitions and interfaces
  274. - **`src/type-guards.ts`**: Runtime type validation functions
  275. - **`src/validation.ts`**: Input validation and sanitization
  276. - **`src/errors.ts`**: Custom error types with structured handling
  277. - **`src/cache.ts`**: In-memory caching for performance optimization
  278. #### Modular Tool Organization
  279. - **`src/tools/`**: Domain-specific MCP tool definitions organized by functionality:
  280. - `task-tools.ts` - Task management (9 tools)
  281. - `subtask-tools.ts` - Subtask operations (5 tools)
  282. - `project-tools.ts` - Project/section management (4 tools)
  283. - `comment-tools.ts` - Comment operations (2 tools)
  284. - `label-tools.ts` - Label management (5 tools)
  285. - `reminder-tools.ts` - Reminder operations (4 tools)
  286. - `test-tools.ts` - Testing and validation (3 tools)
  287. - `index.ts` - Centralized exports
  288. #### Business Logic Handlers
  289. - **`src/handlers/`**: Domain-separated business logic modules:
  290. - `task-handlers.ts` - Task CRUD and bulk operations
  291. - `subtask-handlers.ts` - Hierarchical task management
  292. - `project-handlers.ts` - Project and section operations
  293. - `comment-handlers.ts` - Comment creation and retrieval
  294. - `label-handlers.ts` - Label CRUD and statistics
  295. - `reminder-handlers.ts` - Reminder CRUD via Sync API
  296. - `test-handlers.ts` - API testing infrastructure
  297. - `test-handlers-enhanced/` - Comprehensive CRUD testing framework
  298. #### Utility Modules
  299. - **`src/utils/`**: Shared utility functions:
  300. - `api-helpers.ts` - API response handling utilities
  301. - `error-handling.ts` - Centralized error management
  302. - `parameter-transformer.ts` - MCP to Todoist SDK parameter format conversion
  303. - `dry-run-wrapper.ts` - Dry-run mode implementation
  304. ## Changelog
  305. See [CHANGELOG.md](CHANGELOG.md) for a detailed history of all changes.
  306. For migration guides and breaking changes, see the full changelog.
  307. ## Contributing
  308. Contributions are welcome! This project is actively maintained and I appreciate the community's interest in improving it.
  309. ### A Note on AI-Assisted Contributions
  310. I use [Claude Code](https://docs.anthropic.com/en/docs/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.
  311. 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.
  312. 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.
  313. ### PR Requirements
  314. Before submitting a pull request, please ensure:
  315. 1. **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.
  316. 2. **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.
  317. 3. **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.
  318. 4. **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.
  319. 5. **CI must pass.** PRs with failing CI checks will not be reviewed until they're green.
  320. ### What Makes a Good PR
  321. - A clear, descriptive title and body explaining *what* and *why*
  322. - A focused diff that's easy to review (under 200 lines changed is ideal)
  323. - Tests that demonstrate the change works
  324. - Updated documentation if the change affects user-facing behavior
  325. - No unrelated formatting changes, refactors, or "while I'm here" improvements
  326. ### Getting Started
  327. 1. Fork the repository
  328. 2. Create a feature branch from `main`
  329. 3. Make your changes following the guidelines above
  330. 4. Run `npm run build && npm test && npm run lint` to verify
  331. 5. Submit your PR with a clear description
  332. If 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.
  333. ## License
  334. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  335. ## Issues and Support
  336. If you encounter any issues or need support, please file an issue on the [GitHub repository](https://github.com/greirson/mcp-todoist/issues).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.