Py Todoist

You can run a Python-based MCP server to manage Todoist tasks and projects through the Model Context Protocol. This server lets your AI assistants create, read, update, complete, and delete tasks, manage nested projects, and query with Todoist-style filters, all powered by a robust Python implementation.

How to use

You interact with the server by running it in your environment and connecting to it from an MCP client. Start the server using the runtime commands shown below, then issue natural language requests to manage tasks and projects. The server reads your Todoist API token from the environment, so ensure you set that before starting.

How to install

Prerequisites you need before installing and running the MCP server:

# 1) Install the MCP server via UV
uv tool install git+https://github.com/chris-jelly/py-todoist-mcp.git

# 2) Set up your API token (read from environment)
# Add this to your shell profile (e.g., ~/.bashrc or ~/.zshrc)
export TODOIST_API_TOKEN="your-api-token-here"

Additional sections

Configuration and running details are provided to help you get started. The server reads the Todoist API token from the environment, so you should securely provide it in your shell environment rather than in configuration files. The final command you use to start the server is shown below.

# Start the MCP server using UV
uv run todoist-mcp

This runs the Python MCP server and exposes an MCP channel that your client can connect to for task and project management via Todoist.

## Notes on configuration and usage

Environment variable to configure:
- TODOIST\_API\_TOKEN: Your private Todoist API token. The server automatically reads this from your environment. Do not embed tokens in configuration files.

## Troubleshooting

If you encounter issues starting or connecting to the server, verify the following:
- The TODOIST\_API\_TOKEN is correctly set in your environment.
- You are using a compatible Python version (3.14+).
- UV is installed and available on your PATH.

## Tools and capabilities

You can perform a range of tasks and project operations using the MCP endpoints exposed by this server. The available capabilities include listing, creating, updating, and deleting tasks and projects, as well as querying with filters.

## Available tools

### todoist\_get\_tasks

List tasks with optional filters (project\_id, filter\_string)

### todoist\_get\_task

Get a single task by ID with full details

### todoist\_add\_task

Create a new task with content, description, due\_date, priority, project\_id, labels

### todoist\_update\_task

Update task attributes by ID

### todoist\_complete\_task

Mark a task as complete by ID

### todoist\_delete\_task

Delete a task by ID

### todoist\_get\_projects

List all projects

### todoist\_get\_project

Get a single project by ID with full details

### todoist\_add\_project

Create a new project with name, color, parent\_id

### todoist\_update\_project

Update project attributes by ID

### todoist\_delete\_project

Delete a project by ID