Taskmaster Todoist MCP

🚀 Task Manager: 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 interact directly with your Todoist tasks from your coding environment.

🚀 Quick Start

This is a Todoist Model Context Protocol (MCP) server implementation tailored for Cursor AI. It enables the Cursor AI assistant to interact with your Todoist tasks directly within your coding environment.

🎥 Demo Video

✨ Features

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

Running the Server

python server.py

MCP Tools

The server provides the following MCP tools:

get_tasks_tool

Get tasks with powerful filtering options.

Parameters:

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

Example filtering strings:

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

Using with Cursor AI

To use with 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": [
        "server.py"
      ],
      "env": {
        "TODOIST_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Replace <username> with your actual username and path/to/todoist-mcp with the actual installation path.

📚 Documentation

Project Structure

• api/ - Contains code for interacting with the Todoist API.
• tasks/ - Contains task logic and handlers.
• server.py - The main server file.
• requirements.txt - A list of project dependencies.
• README.md - The project documentation.

Future Plans

• Add task creation functionality.
• Implement task completion functionality.
• Support task deletion operations.
• Increase full support for task priority.
• Provide more complex filtering options.

📄 License

This project is licensed under the MIT License.