Allows AI assistants to manage Todoist tasks and projects, including capabilities to create, read, update, complete, and delete tasks, manage nested projects, and query data using Todoist's filter syntax.
Click on "Install 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., "@py-todoist-mcpCreate a new task 'Call the dentist' for tomorrow at 3pm"
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.
py-todoist-mcp
A Python MCP (Model Context Protocol) server for Todoist integration, enabling AI assistants to manage tasks and projects via the Model Context Protocol.
Features
Task Management: Create, read, update, complete, and delete tasks
Project Management: Manage Todoist projects with support for nested projects
Filter Support: Query tasks using Todoist's powerful filter syntax
Error Handling: Robust error handling with user-friendly messages
Structured Logging: Comprehensive logging for debugging and monitoring
Prerequisites
Python 3.14 or higher
uv for Python package management
A Todoist API token
Installation
1. Install with uv
This installs todoist-mcp into an isolated environment and makes it available globally on your PATH.
2. Set up your API token
The server reads TODOIST_API_TOKEN from the environment. Add it to your shell profile (~/.bashrc, ~/.zshrc, etc.):
To obtain your Todoist API token:
Log in to Todoist
Go to Settings → Integrations → Developer
Copy your API token
Note: Avoid placing your API token directly in MCP configuration files. These files are easy to accidentally commit or share. The server will pick up the token from your environment automatically.
Configuration
Opencode
Add the following to ~/.config/opencode/opencode.json:
Codex
Add the following to your Codex configuration file (location varies by installation):
Usage
Once configured, you can use natural language to interact with Todoist:
Task Examples
Project Examples
Filter Examples
Available Tools
Task Tools
Tool | Description |
| List tasks with optional filters (project_id, filter_string) |
| Get a single task by ID with full details |
| Create a new task with content, description, due_date, priority, project_id, labels |
| Update task attributes by ID |
| Mark a task as complete by ID |
| Delete a task by ID |
Project Tools
Tool | Description |
| List all projects |
| Get a single project by ID with full details |
| Create a new project with name, color, parent_id |
| Update project attributes by ID |
| Delete a project by ID |
Development
Setup
Running the server locally
Code Quality
This project uses Ruff for linting and formatting:
Project Structure
License
MIT License - see LICENSE file for details.
Contributing
Contributions are welcome! Please ensure:
All code passes
ruff lintandruff formatchecksFollow the existing code patterns and conventions
Add tests for new functionality
Update documentation as needed
Troubleshooting
Server won't start
Verify
TODOIST_API_TOKENis set correctlyCheck that Python 3.14+ is installed:
python --versionEnsure uv is installed:
uv --version
Authentication errors
Verify your API token is correct and hasn't expired
Check that your Todoist account is active
Ensure the token has appropriate permissions
AI Assistant not connecting
For Opencode:
Verify the configuration JSON syntax
Check the Opencode logs:
~/.config/opencode/logs/Run
opencode --versionto ensure it's installed correctlyRestart Opencode after configuration changes
For Codex:
Verify the configuration JSON syntax
Check Codex output for error messages
Restart Codex after configuration changes