Todoist MCP Server

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

Quick Start

Install: npm install -g @greirson/mcp-todoist
Get your Todoist API token
Add to Claude Desktop config with your token
Ask Claude: "Show me my Todoist projects"

That's it! You can now manage your Todoist tasks directly through Claude.

Features

Complete Task Management: Create, read, update, delete, and complete tasks with full attribute support
Hierarchical Subtasks: Create subtasks, convert tasks to subtasks, promote subtasks, and view task hierarchies with completion tracking
Bulk Operations: Efficiently create, update, delete, or complete multiple tasks at once
Comment System: Add comments to tasks and retrieve comments with attachment support
Label Management: Full CRUD operations for labels with usage statistics and analytics
Project & Section Organization: Create and manage projects and sections
Enhanced Testing: Basic API validation and comprehensive CRUD testing with automatic cleanup
Smart Discovery: List projects and sections to find IDs for organization
Rich Task Attributes: Support for descriptions, due dates, priorities, labels, deadlines, and project assignment
Natural Language Interface: Use everyday language to manage your Todoist workspace
Performance Optimized: 30-second caching for GET operations to reduce API calls
Robust Error Handling: Structured error responses with custom error types
Input Validation: Comprehensive validation and sanitization of all inputs
Type Safety: Full TypeScript implementation with runtime type checking

Installation & Setup

Step 1: Install the Package

npm install -g @greirson/mcp-todoist

Step 2: Get Your Todoist API Token

Log in to your Todoist account
Go to Settings → Integrations
Scroll down to the Developer section
Copy your API token (keep this secure!)

Step 3: Configure Claude Desktop

Add the server to your Claude Desktop configuration file:

On macOS/Linux:

File location: ~/.config/claude_desktop_config.json

On Windows:

File location: %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "todoist": {
      "command": "mcp-todoist",
      "env": {
        "TODOIST_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

⚠️ Important: Replace your_api_token_here with your actual Todoist API token from Step 2.

Step 4: Restart Claude Desktop

Close and reopen Claude Desktop to load the new MCP server.

Step 5: Verify Installation

In Claude Desktop, try asking:

"Show me my Todoist projects"

You should see a list of your Todoist projects, confirming the integration is working!

Tools Overview

The server provides 28 tools organized by entity type:

Task Management

Todoist Task Create: Create new tasks with full attribute support
Todoist Task Get: Retrieve and filter tasks by various criteria, or fetch specific task by ID
Todoist Task Update: Update existing tasks (found by ID or partial name search)
Todoist Task Complete: Mark tasks as complete (found by ID or partial name search)
Todoist Task Delete: Remove tasks (found by ID or partial name search)

Subtask Management

Todoist Subtask Create: Create subtasks under parent tasks with full attribute support
Todoist Subtasks Bulk Create: Create multiple subtasks under a parent task efficiently
Todoist Task Convert to Subtask: Convert existing tasks to subtasks of another task
Todoist Subtask Promote: Promote subtasks to main tasks (remove parent relationship)
Todoist Task Hierarchy Get: View task hierarchies with subtasks and completion tracking

Bulk Task Operations

Todoist Tasks Bulk Create: Create multiple tasks at once for improved efficiency
Todoist Tasks Bulk Update: Update multiple tasks based on search criteria
Todoist Tasks Bulk Delete: Delete multiple tasks based on search criteria
Todoist Tasks Bulk Complete: Complete multiple tasks based on search criteria

Comment Management

Todoist Comment Create: Add comments to tasks with optional file attachments
Todoist Comment Get: Retrieve comments for tasks or projects

Label Management

Todoist Label Get: List all labels with their IDs and colors
Todoist Label Create: Create new labels with optional color and ordering
Todoist Label Update: Update existing labels (name, color, order, favorite status)
Todoist Label Delete: Remove labels from your workspace
Todoist Label Stats: Get detailed usage statistics for all labels

Project Management

Todoist Project Create: Create new projects with optional color and favorite status
Todoist Project Get: List all projects with their IDs and names

Section Management

Todoist Section Create: Create sections within projects
Todoist Section Get: List sections within projects

Testing & Validation

Todoist Test Connection: Validate API token and test connectivity
Todoist Test All Features: Two modes - basic (read-only API tests) and enhanced (full CRUD testing with cleanup)
Todoist Test Performance: Benchmark API response times with configurable iterations

Troubleshooting

Common Issues

"No Todoist projects found" or connection errors:

Verify your API token is correct
Check that the token is properly set in your claude_desktop_config.json
Ensure there are no extra spaces or quotes around your token

MCP server not loading:

Confirm the package is installed globally: npm list -g @greirson/mcp-todoist
Restart Claude Desktop completely
Check the configuration file path is correct for your operating system

Permission errors:

On macOS/Linux, you may need to create the config directory: mkdir -p ~/.config
Ensure Claude Desktop has permission to read the config file

Usage Examples

Project & Section Setup

"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"

Task Creation & Management

"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 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"
"Delete task ID 1234567890"

Subtask Management

"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"

Bulk Operations

"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"

Comment Management

"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"

Label Management

"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"

Task Discovery

"Show all my tasks"
"List high priority tasks due this week"
"Get tasks in project 12345"

Testing & Validation

"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"

Getting Started Workflow

1. First Steps

"Test my Todoist connection"
"Show me all my Todoist projects"
"Create a new project called 'Claude Integration Test'"

2. Basic Task Management

"Create a task 'Try out MCP integration' in my Inbox"
"Add a high priority task 'Review project setup' due tomorrow"
"Show me all my tasks"

3. Advanced Organization

"Create a section called 'In Progress' in my work project"
"Move the setup task to the In Progress section"
"Add a comment 'This is working great!' to my test task"

4. Bulk Operations

"Create multiple tasks: 'Plan meeting agenda', 'Prepare slides', 'Send invites'"
"Complete all tasks containing 'test' in the Claude project"
"Update all high priority tasks to be due next week"

Best Practices

Start Simple: Begin with basic task creation and project viewing
Use Natural Language: Ask questions as you normally would
Leverage Bulk Operations: Use bulk tools when working with multiple tasks
Organize First: Set up projects and sections before creating many tasks
Regular Cleanup: Use bulk operations to clean up completed or outdated tasks

Development

Building from source

# 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

# 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)
- 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
- 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

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! Feel free to submit a Pull Request.

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.

Install Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

An MCP server that connects Claude with Todoist for complete task and project management through natural language.

Related MCP Servers

Notion MCP
danhilse
-
security
A
license
-
quality
A simple Model Context Protocol (MCP) server that integrates with Notion's API to manage my personal todo list through Claude.
Last updated -
117
Python
MIT License
Todoist MCP Server
abhiz123
A
security
A
license
A
quality
An MCP server that integrates Claude with Todoist, enabling natural language task management including creating, updating, completing, and deleting tasks.
Last updated -
5
245
153
JavaScript
MIT License
Todoist MCP
Doist
A
security
A
license
A
quality
An MCP server that enables LLMs to interact with Todoist tasks, projects, and other features through the Todoist API.
Last updated -
36
121
66
TypeScript
MIT License
MCP Todoist
dkeesey
-
security
F
license
-
quality
A Model Context Protocol server that enables Claude to interact with your Todoist account, allowing you to manage tasks, projects, and labels through natural language.
Last updated -
1
Python

View all related MCP servers