# Todoist MCP Server
Unofficial MCP server for Todoist that allows agents to create, and list tasks in your Todoist account.
## Features
- **Create tasks** with descriptions, due dates, priorities, and labels and projects.
- **List tasks** List completed or uncompleted tasks with filtering by project or Todoist filters.
Works with Claude Desktop, Cursor, and other MCP clients
## Installation
```bash
pip install todoist-mcp-server
```
## Setup
### 1. Get Your Todoist API Token
1. Go to [Todoist Integrations Settings](https://todoist.com/prefs/integrations)
2. Scroll down to "API token"
3. Copy your API token (keep it secure!)
### 2. Configure Your MCP Client
## Usage Examples
Here are some examples of how to use the Todoist MCP server with different clients:
### Claude Desktop
Add this to your `claude_desktop_config.json` file: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows)
```json
{
"mcpServers": {
"todoist": {
"command": "todoist-mcp-server",
"env": {
"TODOIST_API_TOKEN": "your-api-token-here"
}
}
}
}
```
#### Cursor
Add this to your Cursor settings:
1. Open Cursor Settings (`Cmd/Ctrl + ,`)
2. Search for "MCP"
3. Add the MCP server configuration:
```json
{
"mcpServers": {
"todoist": {
"command": "todoist-mcp-server",
"env": {
"TODOIST_API_TOKEN": "your-api-token-here"
}
}
}
}
```
#### Other MCP Clients
For any MCP-compatible client, use:
- **Command:** `todoist-mcp-server`
- **Environment Variable:** `TODOIST_API_TOKEN=your-token`
### 3. Restart Your Client
Restart Claude Desktop, Cursor, or your MCP client to load the server.
## Usage
Once configured, you can interact with Todoist using natural language:
### Creating Tasks
- "Create a task to buy groceries"
- "Add a task 'Call dentist' due tomorrow with high priority"
- "Create a task to finish the report with description 'Include Q4 metrics' due next Friday"
### Listing Tasks
- "Show me my tasks for today"
- "List all my high priority tasks"
- "What tasks do I have in my Work project?"
## Available Tools
### `create_task`
Create a new task in Todoist.
**Parameters:**
- `content` (required): Task title/content
- `description` (optional): Task description
- `project_name` (optional): Project name to add task to
- `due_string` (optional): Due date in natural language ("tomorrow", "next monday")
- `priority` (optional): Priority level 1-4 (1=low, 2=medium, 3=high, 4=urgent)
- `labels` (optional): List of label names
### `list_active_tasks`
List active tasks from Todoist.
**Parameters:**
- `project_name` (optional): Filter by project name
- `filter_string` (optional): Todoist filter ("today", "overdue", "p1")
- `limit` (optional): Maximum number of tasks (default: 50)
## Troubleshooting
### "Server disconnected" Error
1. Make sure you've installed the package: `pip install todoist-mcp-server`
2. Verify your API token is correct
3. Check that the config file is in the right location
4. Restart your MCP client completely
### "Command not found" or "ENOENT" Error
The most common cause is that your MCP client can't find the `todoist-mcp-server` command in its PATH.
**Solution: Use the full path to the command**
1. Find where the command is installed:
```bash
which todoist-mcp-server
```
2. Use the full path in your MCP config:
```json
{
"mcpServers": {
"todoist": {
"command": "/full/path/to/todoist-mcp-server",
"env": {
"TODOIST_API_TOKEN": "your-api-token-here"
}
}
}
}
```
**Other fixes:**
- Ensure the package is installed in the same Python environment your MCP client uses
- Try reinstalling: `pip uninstall todoist-mcp-server && pip install todoist-mcp-server`
### API Token Issues
- Get a fresh token from [Todoist Integrations](https://todoist.com/prefs/integrations)
- Make sure there are no extra spaces in your config file
- Verify the token has the necessary permissions
## Development
To contribute or run from source:
```bash
git clone https://github.com/mehularora8/todoist-mcp
cd todoist-mcp
pip install -e .
```
## Security
- Your API token is stored locally and only used to communicate with Todoist's API
- No data is sent to third parties
- The MCP server runs locally on your machine
## License
MIT License - see LICENSE file for details.
## Support
- 🐛 **Issues:** Report bugs or request features
- 📖 **Todoist API:** [Official Documentation](https://developer.todoist.com/rest/v2/)
- 🔧 **MCP Protocol:** [Model Context Protocol](https://modelcontextprotocol.io/)
---
**Note:** This is an unofficial integration and is not affiliated with Todoist or Doist Inc.
