Todoist MCP Server
A Model Context Protocol (MCP) server that allows clients like Claude to interact with Todoist, enabling task management capabilities through natural language. The server acts as an intermediary between clients and the Todoist API, handling authentication, data transformation, and command processing. This is a Python version
Features
- Task Creation: Create new tasks with required content and optional attributes
- Task Retrieval: Get task by ID or list tasks with filtering options
- Task Management: Update task attributes, mark tasks as complete, delete tasks
Prerequisites
- Python 3.12
- uv
- A Todoist account and API token
How to get Todoist API Token
- Login to your Todoist account
- Go to User Settings -> Integrations -> Developer
- Copy API token
Usage with Claude Desktop
Run via UVX (without cloning)
You can run the server directly from GitHub using UVX:
uvx --from https://github.com/Johnxjp/todoist-mcp-python.git mcp-server-todoist
Then add this configuration to your Claude settings:
{
"mcpServers": {
"todoist-server": {
"command": "uvx",
"args": [
"--from",
"https://github.com/Johnxjp/todoist-mcp-python.git",
"mcp-server-todoist"
],
"env": {
"TODOIST_API_TOKEN": "YOUR_API_TOKEN"
}
}
}
}
Run from cloned repository
If you prefer to clone the repository, use these commands:
git clone git@github.com:Johnxjp/todoist-mcp-python.git
Then add to your Claude config file:
{
"mcpServers": {
"todoist-server": {
"command": "uv",
"args": [
"run",
"--with",
"mcp[cli]",
"--with",
"todoist_api_python",
"mcp",
"run",
"/full/path/to/todoist_server.py"
],
"env": {
"TODOIST_API_TOKEN": "YOUR_API_TOKEN"
}
}
}
}
Available Tools
The server provides the following tools for Claude to use:
-
create_task: Create a new task in Todoist
- Required: content (title of the task)
- Optional:
- description,
- due_date,
- priority,
- project_id,
- section_id,
- labels
-
get_tasks: Get a list of tasks and Ids from Todoist with various filters
- Optional:
- project_id,
- project_name,
- task_name,
- priority,
- labels,
- is_overdue,
- limit
- Optional:
-
update_task: Update an existing task by searching for it by name
- Required: task_id
- Optional:
- content,
- description,
- labels,
- priority,
- due_date (YYYY-MM-DD),
- deadline_date (YYYY-MM-DD)
-
delete_task: Delete a task by searching for it by name
- Required: task_id
-
complete_task: Mark a task as complete by searching for it by name
- Required: task_id
Example Interactions
Here are some examples of how Claude can interact with Todoist through this MCP server:
- "Add a task to buy groceries"
- "Show me all my urgent tasks"
- "What tasks are due today?"
- "Mark the laundry task as done"
- "Change the priority of my dentist appointment to urgent"
Security Considerations
- The server securely handles your Todoist API token through environment variables
- Never share your
.envfile or expose your API token - The server runs locally and communicates only with the Todoist API