Todoist MCP Server

A Model Context Protocol (MCP) server for integrating with the Todoist API. This server provides tools to manage projects, tasks, comments, sections, labels, and user information.

Features

• Projects: Create, read, update, delete, archive, and unarchive projects

• Tasks: Create, read, update, delete, close, and reopen tasks with support for due dates, priorities, labels, and assignments

• Comments: Create, read, update, and delete comments on tasks and projects

• Sections: Create, read, update, and delete sections within projects

• Labels: Create, read, update, and delete labels

• User: Get user information

Prerequisites

• Node.js 18+ (required for native fetch API support)

• A Todoist API token (get one from Todoist Settings > Integrations)

Installation

1. Clone or download this repository

2. Install dependencies:

npm install

3. Build the project:

npm run build

Note: If you encounter TypeScript errors about fetch or URLSearchParams not being found, this is expected during development. These are built-in to Node.js 18+ and will work correctly at runtime. The errors should resolve after installing dependencies.

Configuration

Set the TODOIST_API_TOKEN environment variable with your Todoist API token:

export TODOIST_API_TOKEN="your-api-token-here"

Or create a .env file (you'll need to install dotenv package if you want to use it):

TODOIST_API_TOKEN=your-api-token-here

Usage

Running the Server

The server communicates via stdio (standard input/output) as per MCP protocol:

npm start

Or for development:

npm run dev

MCP Client Configuration

To use this server with an MCP client (like Claude Desktop, Cursor, etc.), configure it in your MCP settings. Example configuration:

{
  "mcpServers": {
    "todoist": {
      "command": "node",
      "args": ["/path/to/todoist-mcp/dist/index.js"],
      "env": {
        "TODOIST_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Available Tools

Projects

• get_projects - Get all active projects (supports pagination)

• get_project - Get a specific project by ID

• create_project - Create a new project

• update_project - Update an existing project

• delete_project - Delete a project

• archive_project - Archive a project

• unarchive_project - Unarchive a project

Tasks

• get_tasks - Get tasks (supports filtering by project, section, label, and pagination)

• get_task - Get a specific task by ID

• create_task - Create a new task

• update_task - Update an existing task

• delete_task - Delete a task

• close_task - Close/complete a task

• reopen_task - Reopen a completed task

Comments

• get_comments - Get comments (supports filtering by project/task and pagination)

• create_comment - Create a comment on a task or project

• update_comment - Update a comment

• delete_comment - Delete a comment

Sections

• get_sections - Get sections (supports filtering by project and pagination)

• create_section - Create a new section

• update_section - Update a section

• delete_section - Delete a section

Labels

• get_labels - Get all labels (supports pagination)

• create_label - Create a new label

• update_label - Update a label

• delete_label - Delete a label

User

• get_user - Get current user information

Examples

Creating a Task

{
  "name": "create_task",
  "arguments": {
    "content": "Buy groceries",
    "project_id": "1234567890",
    "due_string": "tomorrow",
    "priority": 2,
    "labels": ["shopping", "personal"]
  }
}

Getting All Projects

{
  "name": "get_projects",
  "arguments": {
    "limit": 50
  }
}

Creating a Project

{
  "name": "create_project",
  "arguments": {
    "name": "My New Project",
    "color": "berry_red",
    "view_style": "board"
  }
}

API Documentation

For detailed API documentation, see the Todoist API v1 Documentation.

License

MIT