Todoist TaskMaster

🚀 Task Master: Todoist MCP for Cursor AI

A Todoist Model Context Protocol (MCP) server implementation designed specifically for Cursor AI. This server allows the Cursor AI assistant to directly interact with your Todoist tasks from your programming environment.

🎥 Demo Video

✨ Features

• Flexible Task Filtering: Filter tasks using Todoist's powerful filtering syntax.
  • Filter by due date: today, tomorrow, overdue.
  • Filter by priority level (1 - 4, where 1 is the highest).
  • Filter using complex query combinations.
• Rich Task Formatting: Each task displays priority, due date, and other relevant information with clear icons.
• Integration with Cursor AI: Seamlessly use Todoist in your Cursor AI programming environment.

📦 Installation

Prerequisites

• Python 3.10 or higher.
• Poetry (for dependency management).
• A Todoist account and API token.

Setup

1. Clone this repository:

git clone https://github.com/mingolladaniele/todoist-mcp.git
cd todoist-mcp

2. Install dependencies:

pip install -r requirements.txt

3. Set your Todoist API token as an environment variable:

# Linux/macOS
export TODOIST_API_TOKEN="your-api-token-here"

# Windows
set TODOIST_API_TOKEN="your-api-token-here"

You can find your Todoist API token in Todoist Settings → Integrations → Developers.

💻 Usage Examples

Run the Server

python server.py

MCP Tools

The server provides the following MCP tools:

get_tasks_tool

Retrieve tasks with powerful filtering options.

Parameters:

• filter_string: Todoist's advanced filtering query string for complex filtering.
• priority: Optional priority level (1 - 4, where 1 is the highest priority).

Example filter strings:

• "today" - Tasks due today.
• "overdue" - Overdue tasks.
• "Jan 3" - Tasks due on January 3, 2024.
• "due before: May 5" - Tasks due before May 5, 2024.
• "due after: May 5" - Tasks due after May 5, 2024.
• "due before: +4 hours" - Tasks due in the next four hours and all overdue tasks.
• "no date" - Tasks with no due date.
• "5 days" or "next 5 days" - Tasks due in the next five days.
• "recurring" - Tasks with recurring dates.

Set up with Cursor AI

To use it in Cursor AI, create or edit the MCP configuration file:

Windows: C:\Users\<username>\.cursor\mcp.json

{
  "mcpServers": {
    "todoist-mcp": {
      "command": "C:/Users/<username>/path/to/todoist-mcp/.venv/Scripts/python.exe",
      "args": [
        "C:/Users/<username>/path/to/todoist-mcp/server.py"
      ],
      "env": {
        "TODOIST_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Replace <username> with your actual username.

After editing, save the file and restart Cursor. Now you should be able to use Todoist tasks!

📚 Documentation

Project Structure

• api/ - API wrapper.
• config/ - Configuration and settings.
• models/ - Model-related files.
• tasks/ - Task processing logic.
• utils/ - Tools and helper functions.

📄 License

This project is licensed under the MIT license.