Todoist MCP Server

A Model Context Protocol (MCP) server implementation that integrates Claude and other AI assistants with Todoist, enabling natural language task management.

Features

• Complete Todoist API Integration: Access to the full Todoist REST API v2, and support for the Todoist Sync API through natural language
• Batch Processing: Client can process multiple tasks in a single request
• Search by name: AI can search for tasks, projects, and labels by name instead of ID
• Tasks: Create, update, close, reopen, move, and delete tasks using conversational language
• Projects: Create and manage projects and sections
• Comments: Add and manage comments on tasks and projects
• Labels: Create and manage personal and shared labels
• Smart Context: On startup, automatically provides your projects and labels to the AI via server instructions — no extra tool calls needed
• Prompt Support: You can easily provide information about your projects to client

Configuration

You'll need a Todoist API token to use this MCP server.

Getting a Todoist API Token

1. Log in to your Todoist account
2. Navigate to Settings → Integrations
3. Find your API token under "Developer"

Usage

Add to mcpServers in your platform config:

"todoist": {
    "command": "npx",
    "args": ["-y", "todoist-mcp"],
    "env": { "API_KEY": "your_todoist_api_token" }
}

Platform	Config
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\ (Windows)
Claude Code	.mcp.json — claude mcp add --transport stdio --scope project --env API_KEY=token todoist -- npx -y todoist-mcp
Cursor	~/.cursor/mcp.json or .cursor/mcp.json
Codex	~/.codex/config.toml or .codex/config.toml — see example below
Gemini CLI	~/.gemini/settings.json — gemini mcp add -e API_KEY=token todoist npx -y todoist-mcp

Codex — CLI:

codex mcp add todoist --env API_KEY=your_token -- npx -y todoist-mcp

Or add to config.toml:

[mcp_servers.todoist]
command = "npx"
args = ["-y", "todoist-mcp"]

[mcp_servers.todoist.env]
API_KEY = "your_todoist_api_token"

Available Tools

Tasks

• get_tasks_list: Get tasks with optional filtering by project, section, label, or IDs
• get_tasks_by_filter: Get tasks using Todoist filter language (e.g. "today", "overdue", "P1 | P2", "#Work & @urgent")
• create_tasks: Create new tasks with various attributes
• get_tasks: Get specific tasks by ID or name
• update_tasks: Update existing tasks
• close_tasks: Mark tasks as complete
• reopen_tasks: Reopen completed tasks
• delete_tasks: Delete tasks
• move_tasks: Move tasks to a different project or section

Projects

• get_projects_list: Get all projects
• create_projects: Create new projects
• get_projects: Get specific projects by ID or name
• update_projects: Update existing projects
• delete_projects: Delete projects
• get_collaborators: Get all collaborators for a project
• move_projects: Move projects to a different location or subproject

Sections

• get_sections_list: Get all sections or filter by project
• create_sections: Create new sections
• get_sections: Get specific sections by ID or name
• update_sections: Update sections
• delete_sections: Delete sections

Comments

• get_comments_list: Get comments for a project or task
• create_comments: Create new comments
• get_comments: Get specific comments by ID
• update_comments: Update comments
• delete_comments: Delete comments

Labels

• get_labels_list: Get all personal labels
• create_labels: Create new personal labels
• get_labels: Get personal labels by ID or name
• update_labels: Update personal labels
• delete_labels: Delete personal labels
• get_shared_labels: Get all shared labels
• rename_shared_labels: Rename shared labels
• remove_shared_labels: Remove shared labels

Utils

• utils_get_colors: Get available colors for projects, labels, filters

Prompts

• projects_list: Get list of projects with their sections and params in markdown format

Example Usage

Ask your AI assistant (like Claude) questions such as:

"What tasks do I have due today?"
"Create a task to review the quarterly report by next Friday"
"Make a new project called 'Home Renovation'"
"Add a comment to my meeting prep task"
"Show me all my high priority tasks"
"Create a label for 'Urgent' tasks with a red color"
"What projects do I have in my Todoist?"
"Mark my dentist appointment task as complete"

Development

# Install dependencies
npm install

# Build the project and run inspector
npm run build && npx @modelcontextprotocol/inspector -e API_KEY=YOUR_API_KEY_HERE node dist/index.js

License

This project is licensed under the MIT License - see the LICENSE file for details.

Issues and Support

If you encounter any issues or need support, please file an issue on the GitHub repository.