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

Clone or download the server code
Install dependencies:
```
npm install
```
Get your Todoist API token:
- Go to Todoist Integrations
- Copy your API token

Set the environment variable:

export TODOIST_API_TOKEN=your_token_here

Building and Running

# Build the TypeScript code
npm run build

# Run the server
npm start

# Or build and run in one command
npm run dev

# For development with auto-rebuild
npm run watch

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

{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["-y", "@angdrew/todoist-mcp-server"],
      "env": {
        "TODOIST_API_TOKEN": "your_token_here"
      }
    }
  }
}

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

npm run build

Watch Mode

npm run watch

Project Structure

src/
├── index.ts          # Main server implementation
├── types.ts          # TypeScript type definitions (optional)
build/                # Compiled JavaScript output
├── index.js
├── index.d.ts
package.json          # Project dependencies and scripts
tsconfig.json         # TypeScript configuration

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.