Todoist MCP Server

A Model Context Protocol (MCP) server that connects AI assistants to Todoist for seamless task management. This server enables AI assistants to create, read, update, and complete tasks, manage projects, organize sections, and work with labels in your Todoist account.

Why This Tool?

Todoist is one of the most popular task management platforms, helping millions of people organize their work and life. This MCP server brings the power of AI-assisted task management to your workflow, enabling:

Natural Language Task Creation: Create tasks using conversational language
Intelligent Organization: AI can help organize your tasks into projects and sections
Smart Prioritization: Automatically set priorities and due dates based on context
Batch Operations: Perform multiple operations efficiently
Context-Aware Management: AI can understand your task context and suggest improvements

Features

Comprehensive Todoist Integration: Full access to tasks, projects, sections, and labels via the official API
Type-Safe Implementation: Written in TypeScript with comprehensive type definitions
Input Validation: Robust validation for all API inputs using Zod schemas
Error Handling: Graceful error handling with informative messages
Batch Operations: Support for creating, updating, and managing multiple items at once
MCP Integration: Full compatibility with Claude, Cursor, Windsurf, Cline, and other MCP hosts

Available Tools

Task Management

todoist_create_task: Create one or more tasks with full parameter support
- Set content, description, due dates, priorities
- Assign to projects and sections
- Add labels and parent tasks
- Support for duration and deadline fields
todoist_get_tasks: Retrieve tasks with flexible filtering
- Filter by project, section, label, or priority
- Use natural language filters ('today', 'tomorrow', 'overdue')
- Pagination support
todoist_update_task: Update existing tasks by ID or name
- Modify any task property
- Support for batch updates
todoist_move_task: Move tasks to different projects, sections, or parents
- Change task location (use instead of update for moving)
- Move to a different project, section, or make it a subtask
- Support for batch moves
todoist_delete_task: Delete tasks by ID or name
- Support for batch deletion
todoist_complete_task: Mark tasks as complete
- Support for batch completion

Project Management

todoist_get_projects: Retrieve all projects with optional hierarchy
- Include sections for each project
- Filter by specific project IDs
todoist_create_project: Create new projects
- Set colors, view styles (list/board)
- Create nested projects with parent_id
- Mark as favorite
- Optionally create sections during project creation
todoist_update_project: Update existing projects
- Modify name, color, favorite status, view style
- Update by ID or search by name

Section Management

todoist_get_project_sections: Get sections from one or more projects
- Support for batch retrieval
- Find by project ID or name
todoist_create_project_section: Create sections within projects
- Set section name and order
- Support for batch creation

Label Management

todoist_get_personal_labels: Retrieve all personal labels
todoist_get_personal_label: Get a specific label by ID
todoist_create_personal_label: Create new labels
- Set color and favorite status
- Define label order
- Support for batch creation
todoist_update_personal_label: Update existing labels
- Modify name, color, order, favorite status
- Update by ID or search by name
todoist_delete_personal_label: Remove labels from your account

Use Cases

For Personal Productivity

Daily Planning: AI can help organize your day by creating and prioritizing tasks
Inbox Processing: Quickly process task ideas into organized projects
Review & Reflection: AI can analyze your task patterns and suggest improvements

For Knowledge Workers

Meeting Follow-up: Automatically create action items from meeting notes
Project Planning: Break down large projects into manageable tasks and sections
Workload Management: Balance tasks across projects based on priorities and deadlines

For Team Collaboration

Task Delegation: Assign tasks to team members
Project Organization: Create consistent project structures across teams
Progress Tracking: Monitor task completion and project status

Installation

Using Smithery (Recommended)

The easiest way to install Todoist MCP is using Smithery:

# For Claude Desktop
npx -y @smithery/cli install @Hint-Services/mcp-todoist --client claude

# For Cursor
npx -y @smithery/cli install @Hint-Services/mcp-todoist --client cursor

# For Windsurf
npx -y @smithery/cli install @Hint-Services/mcp-todoist --client windsurf

# For Cline
npx -y @smithery/cli install @Hint-Services/mcp-todoist --client cline

Manual Installation

npm install @hoffination/mcp-todoist

Configuration

Add the server to your MCP settings file with the following configuration:

{
  "mcpServers": {
    "todoist": {
      "command": "npx",
      "args": ["-y", "@hoffination/mcp-todoist"],
      "env": {
        "TODOIST_API_TOKEN": "your-todoist-api-token"
      }
    }
  }
}

Required Environment Variables

TODOIST_API_TOKEN: Your Todoist API token (get it here)

Getting Your API Token

Visit Todoist Settings > Integrations > Developer
Sign in to your Todoist account
Scroll to the "API token" section
Copy your API token
Important: Never share your API token or commit it to source control

Example Workflows

Creating a Task

{
  "tool": "todoist_create_task",
  "arguments": {
    "content": "Review quarterly goals",
    "description": "Analyze Q4 performance and set Q1 objectives",
    "due_string": "tomorrow at 2pm",
    "priority": 3,
    "labels": ["work", "planning"]
  }
}

Getting Today's Tasks

{
  "tool": "todoist_get_tasks",
  "arguments": {
    "filter": "today"
  }
}

Creating a Project with Sections

{
  "tool": "todoist_create_project",
  "arguments": {
    "name": "Website Redesign",
    "color": "blue",
    "view_style": "board",
    "sections": ["Design", "Development", "Testing"]
  }
}

Batch Task Creation

{
  "tool": "todoist_create_task",
  "arguments": {
    "tasks": [
      {
        "content": "Design homepage mockup",
        "due_string": "Monday",
        "priority": 4
      },
      {
        "content": "Set up development environment",
        "due_string": "Tuesday"
      },
      {
        "content": "Create component library",
        "due_string": "Wednesday"
      }
    ]
  }
}

Updating Tasks by Name

{
  "tool": "todoist_update_task",
  "arguments": {
    "task_name": "Review quarterly goals",
    "priority": 4,
    "due_string": "today"
  }
}

Moving Tasks to Different Projects

{
  "tool": "todoist_move_task",
  "arguments": {
    "task_id": "6f624qq0GfvXJR9C",
    "project_id": "6XvWFBgqvg9qPVH2"
  }
}

Completing Multiple Tasks

{
  "tool": "todoist_complete_task",
  "arguments": {
    "tasks": [
      { "task_name": "Morning standup" },
      { "task_name": "Email review" },
      { "task_name": "Code review" }
    ]
  }
}

Project Structure

mcp-todoist/
├── src/
│   ├── index.ts          # Main MCP server entry point
│   └── todoist/          # Todoist integration
│       ├── client.ts     # Todoist client implementation
│       └── types.ts      # TypeScript type definitions
├── docs/                 # Documentation
├── package.json          # Project configuration
└── tsconfig.json         # TypeScript configuration

For Developers

Development Commands

pnpm install - Install dependencies
pnpm run build - Build the project for HTTP streaming (default)
pnpm run dev - Run in development mode with hot reloading
pnpm run inspector - Launch MCP inspector for testing (stdio mode)
pnpm run test - Run tests
pnpm run lint:fix - Fix linting issues
pnpm run format:fix - Format code

Deployment Options

HTTP Streaming (Recommended)

pnpm run build:http
pnpm run start:http

Traditional stdio (Legacy)

pnpm run build:stdio
pnpm run start:stdio

The HTTP streaming interface offers better performance and simplified deployment without requiring Docker, while maintaining full backwards compatibility with the traditional stdio interface.

API Reference

The server implements 15 Todoist tools organized into four categories:

Task Tools

todoist_create_task
todoist_get_tasks
todoist_update_task
todoist_move_task
todoist_delete_task
todoist_complete_task

Project Tools

todoist_get_projects
todoist_create_project
todoist_update_project
todoist_get_project_sections
todoist_create_project_section

Label Tools

todoist_get_personal_labels
todoist_get_personal_label
todoist_create_personal_label
todoist_update_personal_label
todoist_delete_personal_label

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

Privacy & Security

Your API token is used only to authenticate with Todoist's official API
No data is stored or cached by this MCP server
All communication is directly between your client and Todoist's servers
Follow Todoist's privacy policy and terms of service

Troubleshooting

API Token Issues

Ensure your API token is valid and not expired
Check that you're using the correct environment variable name: TODOIST_API_TOKEN
Verify your Todoist account has API access enabled

Tasks Not Appearing

Confirm you're querying the correct project or using the right filters
Check that tasks haven't been completed or deleted
Verify project and section IDs are correct

Connection Issues

Check your internet connection
Verify Todoist services are operational
Ensure you're using the latest version of the MCP server

Common Errors

"Task not found": The task name search couldn't find a matching task
"Project not found": Invalid project ID or name
"Invalid color": Use valid Todoist color names (e.g., "blue", "red", "green")

Learn More

For further information, refer to:

Todoist API v1 Documentation: Official API documentation
Model Context Protocol Documentation: MCP architecture and design principles
Smithery - MCP Server Registry: Guidelines for publishing MCP servers
MCP TypeScript SDK Documentation: Comprehensive TypeScript SDK documentation

About Hint Services

"The future is already here, it's just unevenly distributed"

— William Gibson, Author

Hint Services is a boutique consultancy with a mission to develop and expand how user interfaces leverage artificial intelligence technology. We architect ambition at the intersection of AI and User Experience, founded and led by Ben Hofferber.

We offer specialized AI workshops for design teams looking to embrace AI tools without becoming developers. Learn more about our training and workshops.