@gdm-pixel/todoist-mcp

MCP Server for Todoist integration - Complete task management from Claude Desktop.

Manage your Todoist tasks, projects, and productivity directly from Claude. Create, update, complete tasks with natural language, advanced filters, and full API access.

⚠️ Unofficial package - Not affiliated with Todoist. Requires a Todoist API token.

📄 License & Attribution

MIT License - This MCP is free and open-source as it's based on David Miotti's original work.

Enhanced by Charles Annoni - For full Nova-Mind Cloud integration and advanced coaching features, a Nova-Mind Cloud subscription is recommended.

See LICENSE for full terms.

✨ Features

• ✅ Full Task Management - Create, update, complete, delete tasks
• 🗂️ Project Organization - Manage projects and sections
• 🔍 Advanced Filters - Powerful query syntax for finding tasks
• ⚡ Quick Add - Natural language task creation
• 📊 Productivity Stats - Track completed tasks and streaks
• 🏷️ Labels & Priorities - Full support for labels and priority levels
• 📅 Smart Dates - Natural language date parsing ("tomorrow at 3pm")
• 💬 Comments - Add and manage task comments

📦 Installation

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "todoist-official": {
      "command": "npx",
      "args": ["-y", "@gdm-pixel/todoist-mcp@latest"],
      "env": {
        "TODOIST_API_KEY": "your-todoist-api-token"
      }
    }
  }
}

Config location:

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

⚙️ Configuration

Required Environment Variables

| Variable | Description | Example | |----------|-------------|---------| | TODOIST_API_KEY | Your Todoist API token | abc123def456... |

Getting Your API Token

1. Log in to Todoist
2. Go to Settings → Integrations → Developer
3. Copy your API token
4. Paste into your config

🚀 Usage

Create a Task

Add task: "Call client about proposal tomorrow at 2pm #work"

Natural language features:

• Automatic date parsing
• Project detection with #
• Label detection with @
• Priority with p1, p2, p3, p4

Quick Add (Super Fast)

Quick add: "Buy groceries tomorrow @shopping !high"

Supports:

• Natural language dates
• Labels with @
• Priority with !high, !medium, !low
• Projects with #

Complete a Task

Complete the task about calling the client

Search Tasks with Filters

Show me all overdue tasks in the Work project

Filter examples:

• today - Tasks due today
• overdue - All overdue tasks
• #Work - Tasks in Work project
• @email - Tasks with email label
• p1 - Priority 1 (urgent) tasks
• assigned to: me - Tasks assigned to you

Get Productivity Stats

Show me my productivity stats for the last 7 days

Returns:

• Tasks completed per day
• Current streak
• Total completions
• Karma level

📋 Available Tools

Task Management

add-task

Create a new task with full options.

Parameters:

• content (required) - Task description
• projectId (optional) - Project ID
• dueString (optional) - Natural language date ("tomorrow at 3pm")
• priority (optional) - 1-4 (1=normal, 4=urgent)
• labels (optional) - Array of label names
• description (optional) - Task notes

quick-add-task

Fast task creation with natural language.

Parameters:

• text (required) - Full task text with natural language
• note (optional) - Additional notes
• reminder (optional) - Reminder time

update-task

Update an existing task.

Parameters:

• taskId (required) - Task ID
• content (optional) - New description
• dueString (optional) - New due date
• priority (optional) - New priority
• labels (optional) - New labels

close-task

Mark task as complete.

Parameters:

• taskId (required) - Task ID

reopen-task

Reopen a completed task.

Parameters:

• taskId (required) - Task ID

delete-task

Permanently delete a task.

Parameters:

• taskId (required) - Task ID

Searching & Filtering

get-tasks

Get all tasks (optionally filtered by project).

Parameters:

• projectId (optional) - Filter by project

get-tasks-by-filter

Advanced filter using Todoist query syntax.

Parameters:

• filter (required) - Filter string (see Filter Syntax below)

get-task

Get a specific task by ID.

Parameters:

• taskId (required) - Task ID

Projects

get-projects

List all projects.

add-project

Create a new project.

Parameters:

• name (required) - Project name
• color (optional) - Project color
• isFavorite (optional) - Mark as favorite

update-project

Update project properties.

Parameters:

• projectId (required) - Project ID
• name (optional) - New name
• color (optional) - New color

Productivity

get-productivity-stats

Get completion statistics.

Parameters:

• limit (optional) - Days to include (max 30)

get-tasks-completed-by-completion-date

Get tasks completed in a date range.

Parameters:

• since (required) - Start date (YYYY-MM-DD)
• until (required) - End date (YYYY-MM-DD)

🔍 Filter Syntax Guide

Basic Filters

• today - Due today
• tomorrow - Due tomorrow
• overdue - All overdue tasks
• no date - Tasks without due date
• 7 days - Due in next 7 days

Project Filters

• #Work - Tasks in Work project
• ##Work - Work project + sub-projects
• !#Work - Exclude Work project

Label Filters

• @email - Tasks with email label
• @email | @phone - Email OR phone labels
• @work & @urgent - Both work AND urgent labels

Priority Filters

• p1 - Priority 1 (urgent)
• p2 - Priority 2
• p3 - Priority 3
• p4 or no priority - No priority

Date Filters

• date: Jan 3 - Due on specific date
• date before: May 5 - Due before date
• date after: tomorrow - Due after date
• created: today - Created today
• created before: -7 days - Created more than 7 days ago

Assignment Filters

• assigned to: me - Assigned to you
• assigned to: others - Assigned to teammates
• assigned by: me - You assigned to others

Complex Filters

• (today | overdue) & #Work - Today or overdue in Work
• 7 days & @waiting - Due in 7 days with waiting label
• p1 & !#Personal - Priority 1, not in Personal project

🔧 Troubleshooting

Authentication Issues

Problem: "Invalid API token" errors

Solutions:

• Verify API token is correct (copy from Todoist settings)
• Check no extra spaces in the token
• Ensure token hasn't been revoked
• Try regenerating token in Todoist

Tasks Not Updating

Problem: Changes don't appear in Todoist app

Solutions:

• Wait a few seconds (API sync delay)
• Refresh Todoist app
• Check task ID is correct
• Verify you have edit permissions (shared projects)

Filter Returns Nothing

Problem: Filter query returns no results

Solutions:

• Verify filter syntax is correct
• Try simpler filter first (today, overdue)
• Check project/label names match exactly
• Use get-tasks without filter to see all tasks

Natural Language Dates Not Working

Problem: "tomorrow at 3pm" not parsed correctly

Solutions:

• Check date format is supported by Todoist
• Try more explicit format: "2024-12-25 15:00"
• Use date picker format: YYYY-MM-DD
• Verify language setting matches your Todoist account

💡 Pro Tips

Efficient Task Creation

Quick add: "Email John about contract tomorrow 9am #Work @email !high"

→ Creates task with project, label, priority, and due date in one line

Batch Operations

Show me all overdue tasks in Work project, then complete them

→ Filter + bulk actions

Smart Filters

Show tasks created more than 30 days ago with no due date

→ Find forgotten tasks: created before: -30 days & no date

Weekly Review

Show my productivity stats and all tasks due this week

→ Filter: 7 days + get-productivity-stats

📄 License

MIT © Charles Annoni

🔗 Links

• NPM Package
• Todoist Official Site
• Todoist API Documentation
• Report Issues
• MCP Documentation

🙏 Credits

Created by Charles Annoni (GDM-Pixel)

Part of the Nova-Mind ecosystem - AI-powered coaching platform.