Todoist MCP Server
Provides comprehensive task and project management capabilities, allowing users to create, update, complete, and delete tasks, manage projects and sections, and filter tasks by various criteria using Todoist's REST API v2.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Todoist MCP Server show me my tasks due today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Todoist MCP Server
A Model Context Protocol (MCP) server that integrates with Todoist, allowing Claude and other MCP-compatible AI assistants to interact with your Todoist tasks and projects.
Features
Task Management: Create, read, update, complete, and delete tasks
Project Management: List and manage projects
Filtering: Filter tasks by project, section, labels, or natural language queries
Full API Support: Comprehensive coverage of Todoist's REST API v2
Related MCP server: Todoist MCP Server
Installation
Prerequisites
Python 3.12 or higher
pip (Python package installer)
A Todoist account and API token
Step 1: Get Your Todoist API Token
Scroll down to the "API token" section
Copy your API token (you'll need this later)
Step 2: Install the MCP Server
Clone the repository:
git clone <repository-url>
cd todoist-mcpInstall the package:
pip install -e .Note: If you want to install it in a virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -e .Create a
.envfile with your API token:
# Create .env file in the todoist-mcp directory
echo "TODOIST_API_TOKEN=your_api_token_here" > .envReplace your_api_token_here with the token you copied in Step 1.
Step 3: Configure Claude Desktop
The Claude Desktop configuration file is located at:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
Option A: Using Virtual Environment (Recommended for Development)
If you installed in a virtual environment, use the full path to the todoist-mcp command:
{
"mcpServers": {
"todoist": {
"command": "/full/path/to/venv/bin/todoist-mcp"
}
}
}To find the full path, run:
which todoist-mcp # On macOS/Linux
where todoist-mcp # On WindowsOption B: Global Installation
If you installed globally (without a virtual environment), you can use:
{
"mcpServers": {
"todoist": {
"command": "todoist-mcp"
}
}
}Important Notes:
The MCP server will automatically load the
TODOIST_API_TOKENfrom the.envfile in thetodoist-mcpdirectoryYou do NOT need to specify the token in the Claude Desktop config if you're using a
.envfileAfter updating the config, fully restart Claude Desktop (quit the app completely, don't just close the window)
Step 4: Verify Installation
Restart Claude Desktop completely (use Quit from the menu)
Open Claude Desktop
Look for the MCP server indicator (usually in the bottom corner or settings)
You should see "todoist" listed as an available MCP server
Try asking Claude: "Show me my Todoist tasks"
Troubleshooting
"Could not connect to MCP server" or "spawn todoist-mcp ENOENT"
Make sure you used the full path to
todoist-mcpif using a virtual environmentVerify the command exists by running
which todoist-mcp(macOS/Linux) orwhere todoist-mcp(Windows)Check that your
.envfile exists in thetodoist-mcpdirectory with the correct token
"TODOIST_API_TOKEN environment variable not set"
Ensure your
.envfile is in thetodoist-mcpdirectory (same directory aspyproject.toml)Verify the
.envfile contains:TODOIST_API_TOKEN=your_actual_tokenCheck for typos in the variable name
Server keeps disconnecting
Verify your API token is valid at https://todoist.com/app/settings/integrations/developer
Check that you've fully restarted Claude Desktop
Look at Claude Desktop logs for specific error messages
Usage
With Claude Desktop
Once configured, you can interact with Claude using natural language:
"Show me all my tasks for today"
"Create a task to review the quarterly report due tomorrow"
"Mark task ID 12345 as completed"
"List all my projects"
"Create a new project called 'Home Renovation'"
"Show me all high-priority tasks"
As a Standalone Server (Advanced)
You can also run the MCP server directly for testing or integration with other MCP clients:
# Make sure your .env file is configured first
todoist-mcpAvailable Tools
Task Operations
get_tasks- List tasks with optional filteringget_task- Get details of a specific taskcreate_task- Create a new taskupdate_task- Update an existing taskcomplete_task- Mark a task as completedreopen_task- Reopen a completed taskdelete_task- Delete a task
Project Operations
get_projects- List all projectsget_project- Get details of a specific projectcreate_project- Create a new project
Section Operations
get_sections- List sections within projects
Example Interactions
Once connected, you can interact with Claude using natural language:
"Show me all my tasks for today"
"Create a task to review the quarterly report due tomorrow"
"Mark task ID 12345 as completed"
"List all my projects"
"Create a new project called 'Home Renovation'"
Development
Project Structure
todoist-mcp/
├── todoist_mcp/
│ ├── __init__.py
│ ├── client.py # Todoist API client
│ └── server.py # MCP server implementation
├── pyproject.toml
├── README.md
└── .env.exampleRunning Tests
(Tests would be added here in the future)
Contributing
Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request
License
This project is licensed under the terms specified in the LICENSE file.
Available Tools
11 toolscomplete_taskB
Mark a task as completed.
Args:
task_id: The ID of the task to complete
Inputs: task_id (required). Returns: result
create_projectB
Create a new project in Todoist.
Args:
name: The name of the project
parent_id: Parent project ID (for nested projects)
color: Project color
is_favorite: Whether to mark as favorite
Inputs: name (required), parent_id, color, is_favorite. Returns: result
create_taskA
Create a new task in Todoist.
Args:
content: The task content/title
description: Detailed description of the task
project_id: Project ID to add the task to
section_id: Section ID within the project
parent_id: Parent task ID (for subtasks)
labels: List of label names
priority: Priority from 1 (normal) to 4 (urgent)
due_string: Human readable due date (e.g., 'tomorrow', 'next Monday')
due_date: ISO 8601 formatted due date
Inputs: content (required), description, project_id, section_id, +5 more. Returns: result
delete_taskC
Delete a task.
Args:
task_id: The ID of the task to delete
Inputs: task_id (required). Returns: result
get_projectA
Get a specific project by ID.
Args:
project_id: The ID of the project to retrieve
Inputs: project_id (required). Returns: result
get_projectsB
Get all projects from Todoist.
Inputs: no named parameters. Returns: result
get_sectionsC
Get sections from a project.
Args:
project_id: Project ID to get sections from (optional)
Inputs: project_id. Returns: result
get_taskC
Get a specific task by ID.
Args:
task_id: The ID of the task to retrieve
Inputs: task_id (required). Returns: result
get_tasksC
Get tasks from Todoist with optional filtering.
Args:
project_id: Filter tasks by project ID
section_id: Filter tasks by section ID
label: Filter tasks by label
filter_query: Natural language filter (e.g., 'today', 'overdue', 'p1')
Inputs: project_id, section_id, label, filter_query. Returns: result
reopen_taskC
Reopen a completed task.
Args:
task_id: The ID of the task to reopen
Inputs: task_id (required). Returns: result
update_taskB
Update an existing task.
Args:
task_id: The ID of the task to update
content: Updated task content/title
description: Updated task description
labels: Updated list of label names
priority: Updated priority from 1 (normal) to 4 (urgent)
due_string: Updated human readable due date
due_date: Updated ISO 8601 formatted due date
Inputs: task_id (required), content, description, labels, +3 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Every tool has a clearly distinct purpose with no ambiguity. The tools are organized around specific resources (tasks, projects, sections) and actions (create, get, update, delete, complete, reopen), making it easy for an agent to select the right tool. For example, 'complete_task' and 'reopen_task' handle task state changes, while 'update_task' handles content modifications.
All tool names follow a consistent verb_noun pattern throughout, using snake_case. The verbs are clear and appropriate (e.g., create, get, update, delete, complete, reopen), and nouns specify the resource (e.g., task, project, sections). There are no deviations or mixed conventions.
With 11 tools, this server is well-scoped for managing Todoist tasks and projects. Each tool earns its place by covering essential operations like CRUD for tasks and projects, plus specific actions like completing/reopening tasks and retrieving sections. The count is neither too thin nor excessive for the domain.
The tool surface provides complete CRUD/lifecycle coverage for tasks and projects, with no obvious gaps. It includes creation, retrieval, updating, and deletion for both resources, plus state management (complete/reopen) for tasks and section retrieval. This allows agents to handle all core workflows without dead ends.
Maintenance
Related MCP Connectors
Manage tasks, Focus Zone, notes, projects, and task history from compatible AI assistants.
AI-powered to-do list: add, list, complete and organise tasks across lists from any assistant.
Create and manage MeisterTask projects, tasks, and notes from your AI assistant.
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Todoist tasks, projects, labels, sections, and comments through natural conversation. Supports comprehensive task operations including creation, updates, completion, and organization with natural language quick-add functionality.-
- AlicenseNot gradedqualityDmaintenanceConnects AI assistants to Todoist for comprehensive task management, enabling natural language creation, updating, and organization of tasks, projects, sections, and labels.17 npm3MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Todoist tasks, projects, sections, and labels through natural language, supporting task creation, updates, completion, and intelligent organization of your workflow.MIT
- AlicenseAqualityFmaintenanceEnables AI assistants to manage Todoist tasks, projects, and labels through natural language, with support for filters, priorities, and natural language dates.12MIT