# todo-mcp

A todo CLI with a built-in [MCP](https://modelcontextprotocol.io/) server.
The main idea is that you can tell an MCP-compatible AI assistant "add this to
todo" while you're in the middle of something else, and it just works.

Todos are stored in a local SQLite database and can be organized with
priorities, tags, and automatic git project association.

## Install

Requires Rust 1.85+ (edition 2024).

```sh
cargo install --path .
```

## Configuration

Set `TODO_DB` to override the default database path (`~/.local/share/todo/todos.db`).

## Usage

```sh
# add a todo
todo-mcp add "fix the login bug"

# add with priority and tags
todo-mcp add "refactor auth module" -p high -t backend -t tech-debt

# add without associating to the current git repo
todo-mcp add "something general" --no-project

# list open todos
todo-mcp ls

# list todos for the current repo only
todo-mcp ls --here

# filter by tag or priority
todo-mcp ls -t backend
todo-mcp ls -p critical

# search
todo-mcp ls -s "auth"

# mark as done
todo-mcp done 3

# edit text, priority, or tags
todo-mcp edit 3 "updated description"
todo-mcp edit 3 -p low
todo-mcp edit 3 -t new-tag --untag old-tag

# remove permanently
todo-mcp rm 3

# show all tags in use
todo-mcp tags

# clean up completed todos
todo-mcp purge
```

## Docker

```sh
docker build -t local/todo-mcp .
docker run --rm -v todo-mcp-data:/data -e TODO_DB=/data/todos.db local/todo-mcp --help
```

Data is persisted in the `todo-mcp-data` volume. See [Usage](#usage) for more commands.

## Claude Setup

### Native

```json
{
  "mcpServers": {
    "todo": {
      "command": "todo-mcp",
      "args": ["mcp-serve"]
    }
  }
}
```

### Docker

Build the image first (see [Docker](#docker)), then add to your Claude MCP config:

```json
{
  "mcpServers": {
    "todo": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "todo-mcp-data:/data",
        "-e", "TODO_DB=/data/todos.db",
        "local/todo-mcp", "mcp-serve"
      ]
    }
  }
}
```

This gives Claude access to all todo operations — adding, listing, completing,
editing, removing, and purging.