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