diff --git a/README.md b/README.md
index 044a482..f90037a 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,82 @@
-# todo
+# Todo
+
+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 add "fix the login bug"
+
+# add with priority and tags
+todo add "refactor auth module" -p high -t backend -t tech-debt
+
+# add without associating to the current git repo
+todo add "something general" --no-project
+
+# list open todos
+todo ls
+
+# list todos for the current repo only
+todo ls --here
+
+# filter by tag or priority
+todo ls -t backend
+todo ls -p critical
+
+# search
+todo ls -s "auth"
+
+# mark as done
+todo done 3
+
+# edit text, priority, or tags
+todo edit 3 "updated description"
+todo edit 3 -p low
+todo edit 3 -t new-tag --untag old-tag
+
+# remove permanently
+todo rm 3
+
+# show all tags in use
+todo tags
+
+# clean up completed todos
+todo purge
+```
+
+## Claude Setup
+
+Todo ships with an MCP server that lets Claude manage your todos. Add this to
+your Claude MCP config:
+
+```json
+{
+  "mcpServers": {
+    "todo": {
+      "command": "todo",
+      "args": ["mcp-serve"]
+    }
+  }
+}
+```
+
+This gives Claude access to all todo operations — adding, listing, completing,
+editing, removing, and purging.