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

# 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.