todo-mcp

A todo CLI with a built-in MCP 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).

cargo install --path .

Configuration

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

Usage

# 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

A pre-built image is available from GitHub Container Registry:

docker run --rm -v todo-mcp-data:/data -e TODO_DB=/data/todos.db ghcr.io/janezicmatej/todo-mcp --help

Or build locally:

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 for more commands.

Claude Setup

Native

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

Docker

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

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