npm package: @nova-mind-cloud/todoist-mcp
Description: Model Context Protocol server for Todoist - Task and project management
Author: Charles Annoni
Latest version: 1.0.5

# @gdm-pixel/todoist-mcp

[![npm version](https://img.shields.io/npm/v/@nova-mind-cloud/todoist-mcp.svg)](https://www.npmjs.com/package/@nova-mind-cloud/todoist-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**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](https://github.com/davidmiotti).

**Enhanced by Charles Annoni** - For full **Nova-Mind Cloud integration** and advanced coaching features, 
a [Nova-Mind Cloud subscription](https://nova-mind.cloud) is recommended.

See [LICENSE](./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`:

```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](https://todoist.com)
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](https://www.npmjs.com/package/@gdm-pixel/todoist-mcp)
- [Todoist Official Site](https://todoist.com)
- [Todoist API Documentation](https://developer.todoist.com)
- [Report Issues](https://github.com/gdm-pixel/todoist-mcp/issues)
- [MCP Documentation](https://modelcontextprotocol.io)

---

## 🙏 Credits

Created by **Charles Annoni** ([GDM-Pixel](https://gdm-pixel.fr))

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