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

1. Visit Todoist Settings > Integrations > Developer
2. Sign in to your Todoist account
3. Scroll to the "API token" section
4. Copy your API token
5. 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.