# 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.13 or higher
- [uv](https://github.com/astral-sh/uv) for Python package management
- A Todoist API token

## Installation

### 1. Install with uv

```bash
uv tool install git+https://github.com/chris-jelly/py-todoist-mcp.git
```

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.):

```bash
# Add to your shell profile
export TODOIST_API_TOKEN="your-api-token-here"
```

To obtain your Todoist API token:
1. Log in to [Todoist](https://todoist.com)
2. Go to Settings → Integrations → Developer
3. 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`. This uses `uvx` to run the server directly from the git repo — no local install required:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "todoist": {
      "type": "local",
      "command": ["uvx", "--from", "git+https://github.com/chris-jelly/py-todoist-mcp.git", "todoist-mcp"],
      "environment": {
        "TODOIST_API_TOKEN": "{env:TODOIST_API_TOKEN}"
      }
    }
  }
}
```

If you've already installed the package locally (via `uv tool install`), you can use the simpler form:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "todoist": {
      "type": "local",
      "command": ["todoist-mcp"]
    }
  }
}
```

### Codex

Add the following to your Codex configuration file (location varies by installation):

```json
{
  "mcpServers": {
    "todoist": {
      "command": "todoist-mcp"
    }
  }
}
```

## Usage

Once configured, you can use natural language to interact with Todoist:

### Task Examples

```
"Show me all my tasks"
"List my tasks for today"
"Create a task 'Buy groceries' due tomorrow with priority 1"
"Get details for task ID 123456"
"Update task 123456 to be due next Monday"
"Mark task 123456 as complete"
"Delete task 123456"
```

### Project Examples

```
"List all my projects"
"Create a new project called 'Work'"
"Get details for project ID 987654"
"Update project 987654 color to blue"
"Delete project 987654"
```

### Filter Examples

```
"Show me overdue tasks"
"List tasks in project work"
"Get tasks labeled urgent"
```

## Available Tools

### Task Tools

| Tool | Description |
|------|-------------|
| `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 |

### Project Tools

| Tool | Description |
|------|-------------|
| `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 |

## Development

### Setup

```bash
git clone git@github.com:chris-jelly/py-todoist-mcp.git
cd py-todoist-mcp
uv sync
```

### Running the server locally

```bash
uv run todoist-mcp
```

### Code Quality

This project uses [Ruff](https://github.com/astral-sh/ruff) for linting and formatting:

```bash
# Format code
ruff format .

# Check for linting errors
ruff check .

# Fix auto-fixable issues
ruff check . --fix
```

### Project Structure

```
py-todoist-mcp/
├── src/todoist_mcp/
│   ├── __init__.py
│   ├── main.py          # Entry point
│   ├── server.py        # FastMCP server setup
│   ├── client.py        # Todoist API client
│   ├── utils.py         # Logging and error handling
│   └── tools/
│       ├── __init__.py
│       ├── tasks.py     # Task management tools
│       └── projects.py  # Project management tools
├── pyproject.toml
└── README.md
```

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions are welcome! Please ensure:

1. All code passes `ruff lint` and `ruff format` checks
2. Follow the existing code patterns and conventions
3. Add tests for new functionality
4. Update documentation as needed

## Troubleshooting

### Server won't start

- Verify `TODOIST_API_TOKEN` is set correctly
- Check that Python 3.13+ is installed: `python --version`
- Ensure 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 --version` to ensure it's installed correctly
- Restart Opencode after configuration changes

**For Codex:**
- Verify the configuration JSON syntax
- Check Codex output for error messages
- Restart Codex after configuration changes