Todoist MCP Server (TypeScript)

A Model Context Protocol (MCP) server for interacting with the Todoist API. This server provides CRUD operations for both Tasks and Projects through a standardized MCP interface, built with TypeScript and the official MCP SDK.

Features

Project Operations

• ✅ Create new projects

• ✅ Get project details

• ✅ List all projects

• ✅ Update project properties

• ✅ Delete projects

Task Operations

• ✅ Create new tasks

• ✅ Get task details

• ✅ List tasks with filtering

• ✅ Update task properties

• ✅ Complete tasks

• ✅ Reopen completed tasks

• ✅ Delete tasks

Setup

Prerequisites

• Node.js 18+

• npm or yarn

• Todoist API token

Installation

1. Clone or download the server code

2. Install dependencies:

   npm install

3. Get your Todoist API token:

   • Go to Todoist Integrations

   • Copy your API token

4. Set the environment variable:

   export TODOIST_API_TOKEN=your_token_here

Building and Running

Configuration for Claude Desktop

Add the following to your Claude Desktop configuration file:

For macOS: ~/Library/Application Support/Claude/claude_desktop_config.json For Windows: %APPDATA%\\Claude\\claude_desktop_config.json

Available Tools

Project Tools

create_project

Create a new project in Todoist

• name (required): Project name

• color (optional): Project color

• viewStyle (optional): View style ("list" or "board")

• parentId (optional): Parent project ID for sub-projects

• isFavorite (optional): Mark as favorite

get_project

Get project details by ID

• projectId (required): Project ID

list_projects

List all projects (no parameters)

update_project

Update project properties

• projectId (required): Project ID

• name (optional): New name

• color (optional): New color

• viewStyle (optional): New view style

• isFavorite (optional): Favorite status

delete_project

Delete a project

• projectId (required): Project ID

Task Tools

create_task

Create a new task

• content (required): Task content

• description (optional): Task description

• projectId (optional): Project ID

• dueString (optional): Due date in natural language

• dueDate (optional): Due date (YYYY-MM-DD)

• dueDatetime (optional): Due datetime (RFC3339)

• priority (optional): Priority 1-4 (4 is highest)

• labels (optional): Array of labels

get_task

Get task details by ID

• taskId (required): Task ID

list_tasks

List tasks with optional filters

• projectId (optional): Filter by project ID

• filter (optional): Filter expression (e.g., 'today', 'overdue')

• label (optional): Filter by label

update_task

Update task properties

• taskId (required): Task ID

• content (optional): New content

• description (optional): New description

• dueString (optional): New due date

• dueDate (optional): New due date (YYYY-MM-DD)

• dueDatetime (optional): New due datetime

• priority (optional): New priority

• labels (optional): New labels array

complete_task

Mark a task as completed

• taskId (required): Task ID

reopen_task

Reopen a completed task

• taskId (required): Task ID

delete_task

Delete a task

• taskId (required): Task ID

Usage Examples

Once configured with Claude Desktop, you can use natural language commands:

• "Create a new project called 'Website Redesign'"

• "List all my projects"

• "Add a task 'Review mockups' to the Website Redesign project"

• "Show me all tasks due today"

• "Mark task 12345 as completed"

• "Update the task content to 'Review and approve mockups'"

Error Handling

The server includes comprehensive error handling for:

• Invalid API tokens

• Missing required parameters

• API rate limits

• Network errors

• Invalid project/task IDs

Development

Building

Watch Mode

Project Structure

Dependencies

• @modelcontextprotocol/sdk: Official MCP SDK for TypeScript

• @doist/todoist-api-typescript: Official Todoist API TypeScript client

• zod: Schema validation library

License

This project is provided as-is for educational and personal use.