Labsco
greirson logo

Todoist

★ 245

from greirson

Manage tasks and projects on Todoist using natural language.

🔥🔥🔥🔥✓ VerifiedAccount requiredAdvanced setup
#automation#analytics#devops#git#maps

Todoist MCP Server

An MCP (Model Context Protocol) server that connects Claude with Todoist for complete task and project management through natural language.

Features

  • 19 MCP Tools for complete Todoist management
  • Task Management: Create, update, delete, complete, reopen tasks with priorities, due dates, labels
  • Bulk Operations: Process multiple tasks efficiently
  • Subtasks: Hierarchical task management with completion tracking
  • Projects & Sections: Full organization support
  • Labels, Filters, Reminders: Pro/Business features supported
  • Natural Language: Quick add with Todoist's natural language parsing
  • Dry-Run Mode: Test operations without making changes

Dry-Run Mode

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.

How to Enable Dry-Run Mode

Add DRYRUN=true to your environment configuration:

Copy & paste — that's it
{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["@greirson/mcp-todoist"],
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here",
        "DRYRUN": "true"
      }
    }
  }
}

What Dry-Run Mode Does

  • Validates Operations: Uses real API data to validate that operations would succeed
  • Simulates Mutations: Create, update, delete, and complete operations are simulated (not executed)
  • Real Data Queries: Read operations (get tasks, projects, labels) use the real API
  • Detailed Logging: Shows exactly what would happen with clear [DRY-RUN] prefixes
  • Error Detection: Catches the same errors that would occur in real execution

Use Cases

  • Testing Automations: Validate complex bulk operations before executing
  • Learning the API: Explore functionality without fear of making unwanted changes
  • Debugging Issues: Understand what operations would be performed
  • Safe Experimentation: Try new workflows without affecting your actual tasks
  • Training and Demos: Show how operations work without modifying real data

Example Usage

With dry-run mode enabled, operations show what would happen:

Copy & paste — that's it
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)

Supported Operations

All 19 MCP tools support dry-run mode:

  • Task creation, updates, completion, and deletion
  • Subtask operations and hierarchy changes
  • Bulk operations across multiple tasks
  • Project and section creation
  • Label management operations
  • Reminder CRUD operations
  • Comment creation

Disabling Dry-Run Mode

Remove the DRYRUN environment variable or set it to false, then restart Claude Desktop to return to normal operation mode.

Tools Overview

The server provides 19 MCP tools for complete Todoist management:

ToolActionsDescription
todoist_taskcreate, get, update, delete, complete, reopen, quick_addComplete task management
todoist_task_bulkbulk_create, bulk_update, bulk_delete, bulk_completeEfficient multi-task operations
todoist_subtaskcreate, bulk_create, convert, promote, hierarchyHierarchical task management
todoist_projectcreate, get, update, delete, archive, collaboratorsProject CRUD and sharing
todoist_project_opsreorder, move_to_parent, get_archivedAdvanced project operations
todoist_sectioncreate, get, update, delete, move, reorder, archiveSection management
todoist_labelcreate, get, update, delete, statsLabel management with analytics
todoist_commentcreate, get, update, deleteTask/project comments
todoist_remindercreate, get, update, deleteReminder management (Pro)
todoist_filtercreate, get, update, deleteCustom filters (Pro)
todoist_collaborationinvitations, notifications, workspace operationsTeam collaboration features
todoist_userinfo, productivity_stats, karma_historyUser profile and stats
todoist_utilitytest_connection, test_features, test_performance, find/merge duplicatesTesting and utilities
todoist_activityget_log, get_events, get_summaryActivity audit trail
todoist_task_opsmove, reorder, closeAdvanced task operations
todoist_completedget, get_all, get_statsCompleted task retrieval
todoist_backuplist, downloadAutomatic backup access
todoist_notescreate, get, update, deleteProject notes (collaborators)
todoist_shared_labelscreate, get, rename, removeWorkspace labels (Business)

For detailed tool documentation with parameters and examples, see TOOLS_REFERENCE.md.

Development

Building from source

Copy & paste — that's it
# 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

Development Commands

Copy & paste — that's it
# 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

Architecture

The codebase follows a clean, modular architecture designed for maintainability and scalability:

Core Structure

  • src/index.ts: Main server entry point with request routing
  • src/types.ts: TypeScript type definitions and interfaces
  • src/type-guards.ts: Runtime type validation functions
  • src/validation.ts: Input validation and sanitization
  • src/errors.ts: Custom error types with structured handling
  • src/cache.ts: In-memory caching for performance optimization

Modular Tool Organization

  • src/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 exports

Business Logic Handlers

  • src/handlers/: Domain-separated business logic modules:
    • task-handlers.ts - Task CRUD and bulk operations
    • subtask-handlers.ts - Hierarchical task management
    • project-handlers.ts - Project and section operations
    • comment-handlers.ts - Comment creation and retrieval
    • label-handlers.ts - Label CRUD and statistics
    • reminder-handlers.ts - Reminder CRUD via Sync API
    • test-handlers.ts - API testing infrastructure
    • test-handlers-enhanced/ - Comprehensive CRUD testing framework

Utility Modules

  • src/utils/: Shared utility functions:
    • api-helpers.ts - API response handling utilities
    • error-handling.ts - Centralized error management
    • parameter-transformer.ts - MCP to Todoist SDK parameter format conversion
    • dry-run-wrapper.ts - Dry-run mode implementation

Changelog

See CHANGELOG.md for a detailed history of all changes.

For migration guides and breaking changes, see the full changelog.

Contributing

Contributions are welcome! This project is actively maintained and I appreciate the community's interest in improving it.

A Note on AI-Assisted Contributions

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.

PR Requirements

Before submitting a pull request, please ensure:

  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.

  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.

  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.

  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.

  5. CI must pass. PRs with failing CI checks will not be reviewed until they're green.

What Makes a Good PR

  • A clear, descriptive title and body explaining what and why
  • A focused diff that's easy to review (under 200 lines changed is ideal)
  • Tests that demonstrate the change works
  • Updated documentation if the change affects user-facing behavior
  • No unrelated formatting changes, refactors, or "while I'm here" improvements

Getting Started

  1. Fork the repository
  2. Create a feature branch from main
  3. Make your changes following the guidelines above
  4. Run npm run build && npm test && npm run lint to verify
  5. Submit your PR with a clear description

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.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Issues and Support

If you encounter any issues or need support, please file an issue on the GitHub repository.