Todoist MCP Server

A Model Context Protocol (MCP) server for Todoist task management, enabling Claude to interact with your Todoist tasks and projects.

Features

• ✅ Create, read, update, and complete tasks
• 📋 List tasks with advanced filtering
• 🔍 Search tasks by text content
• 📁 Manage projects
• 🏷️ Support for labels and priorities
• 📅 Natural language date parsing
• ⚡ Rate limiting to stay within API limits
• 🛡️ Comprehensive error handling

Installation

Prerequisites

• Node.js >= 18.0.0
• npm or yarn
• A Todoist account with an API token

From Source

# Clone the repository
git clone <your-repo-url>
cd todoist-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

1. Get Your Todoist API Token

1. Go to Todoist Integrations Settings
2. Scroll down to "API token" section
3. Copy your personal API token

2. Set Up Environment Variables

Create a .env file in the project root:

cp .env.example .env

Edit .env and add your Todoist API token:

TODOIST_API_TOKEN=your_actual_token_here
LOG_LEVEL=error

3. Configure Claude Desktop

Add the server to your Claude Desktop configuration file:

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "todoist": {
      "command": "node",
      "args": ["/absolute/path/to/todoist-mcp/build/server.js"],
      "env": {
        "TODOIST_API_TOKEN": "your_actual_token_here"
      }
    }
  }
}

Important: Replace /absolute/path/to/todoist-mcp with the actual absolute path to your project directory.

4. Restart Claude Desktop

After updating the configuration, restart Claude Desktop for the changes to take effect.

Available Tools

todoist_create_task

Create a new task in Todoist with optional project, due date, priority, labels, and parent task for subtasks.

Parameters:

• content (required): The task content/title
• description (optional): Task description
• project_id (optional): Project ID to add the task to
• section_id (optional): Section ID within the project
• due_date (optional): Due date in natural language or YYYY-MM-DD format
• priority (optional): Priority level: 1 (normal), 2 (medium), 3 (high), 4 (urgent)
• labels (optional): Array of label names
• parent_id (optional): Parent task ID to create a subtask
• parent_task_name (optional): Parent task name to search for (alternative to parent_id)

Examples:

Create a task "Write report" due tomorrow with high priority
Create a task "Buy groceries" in the Shopping project
Create a task "Team meeting" due "next Monday at 2pm"
Create a subtask "Buy milk" under parent task "Go to the supermarket"
Create a subtask "Review slides" under task 8237492837
Add subtask "Call John" to the task "Prepare presentation"

todoist_list_tasks

List active tasks with optional filters for project, section, label, or custom Todoist filter.

Parameters:

• project_id (optional): Filter by project ID
• section_id (optional): Filter by section ID
• label (optional): Filter by label name
• filter (optional): Todoist filter query (e.g., "today", "overdue", "p1")
• limit (optional): Maximum number of tasks to return (default: 50, max: 200)

Examples:

List all my tasks
List tasks in project "Work"
List tasks due today
List all overdue tasks with limit 20

todoist_get_task

Get detailed information about a specific task including all metadata.

Parameters:

• task_id (required): The task ID to retrieve

Examples:

Get details for task 123456789
Show me task 987654321

todoist_update_task

Update an existing task with new content, description, due date, priority, or labels.

**Para

... View full README on GitHub