todo-mcp

An MCP server whose store is a TODO.md you can read, edit and diff by hand. Writes are byte-range splices, so the file stays yours: hand-authored tables, tab indentation and any prose outside a task are never re-serialised.

Speaks stdio for MCP clients and Streamable HTTP for everything else.

Credit

Based on CalamityAdam/mcp-todo, which supplied the original scaffold: the createTodoMcpServer factory shape, the Express Streamable HTTP wrapper and the session handling.

Almost nothing else survives. That version kept todos as numbered records in a JSON blob at ~/.mcp-todos.json with three tools over { id, title, done }. This one replaces the store with a markdown document, swaps numeric ids for slugs, and grows the tool surface to seven with statuses, areas, reference breadcrumbs, dated log notes, full-text query and duplicate detection. The two projects no longer share an implementation.

Upstream ships no LICENSE file; its package.json declares ISC, which is what this repo carries forward.

Install

Run it straight from GitHub, no clone:

npx github:adrianhardy/todo-mcp

After pushing any changes, use npx --ignore-existing github:adrianhardy/todo-mcp to pick them up.

For regular use, install once and forget about it:

npm i -g github:adrianhardy/todo-mcp
todo-mcp

Either route builds from source on install via the prepare script, so dist/ is never committed. Node 20 or newer.

Usage

todo-mcp starts the HTTP server by default, because that is the useful thing to do when a person runs it in a terminal. Set MCP_STDIO=1 to speak stdio instead, which is what an MCP client spawning it as a subprocess wants.

With an MCP client

{
  "mcpServers": {
    "todo": {
      "command": "npx",
      "args": ["-y", "github:adrianhardy/todo-mcp"],
      "env": { "MCP_STDIO": "1" }
    }
  }
}

Installed globally, that becomes "command": "todo-mcp" with the same env block.

The working directory decides which file you get. TODO_FILE resolves against the process's cwd and defaults to TODO.md, so a client launched in a project edits that project's todo list. Set TODO_FILE to an absolute path if you want one shared list regardless of where the server starts.

Over HTTP

PORT=8080 TODO_MCP_TOKEN=$(openssl rand -hex 32) todo-mcp

• POST /mcp - JSON-RPC requests
• GET /mcp - SSE stream for server notifications
• DELETE /mcp - end the session

Setting TODO_MCP_TOKEN requires Authorization: Bearer <token> on all three. Leaving it unset disables authentication, which is fine on localhost and nowhere else.

Configuration

variable	default	meaning
TODO_FILE	TODO.md	store path, resolved against cwd
MCP_STDIO	unset	1 selects stdio instead of HTTP
PORT	3000	HTTP port
TODO_MCP_TOKEN	unset	bearer token; unset means no auth

A .env file is read if present. See .env.example.

Storage

TODO.md is the store, not a JSON blob. The file is the record: readable, editable by hand, and diffable in git.

A task is a ## section. Fields the server owns live in a comment block directly under the heading; everything below it is prose the human owns.

## Feature Idea version two: the new widget which tracks things

<!-- todo
id: feature-idea-version-two
area: inventory
status: next
refs: [./src/do_stuff.ts, ClassName.Method, OtherClassName]
created: 2026-08-19
updated: 2026-08-22
-->

**Next step:** close the ledger. ClassName.Method uses 0.25 and it needs 17.2%.

**Already known:** ...

### Log

- 2026-08-22 Slab_Wall_1x3 not started; parade places 24 of those to every 6 of the 3x3.

Ids are slugs, not numbers, so they survive reordering and deletion. File order is priority order, which is why there is no priority field.

Writes are byte-range splices: a mutation rewrites only the span it owns. Hand-authored tables, tab indentation and any prose outside a task section are never re-serialised, so they cannot be reflowed or lost. Handlers are serialised through a lock, because two interleaved read-modify-write cycles would splice against offsets that no longer describe the file.

Design

• list is abbreviated list_todos returns a one-line index and never task bodies. get_todo returns one whole section. q or ref is the expected path; listing everything is the exception.
• Capture takes one field. Only title is required, and new tasks default to status captured. A tool that demands an area and a next step at the moment something is noticed does not get used, and the file only earns its keep if things get written down as they are found. Triage moves captured to open/next/parked/someday later.

Status values

status	meaning
captured	raw, untriaged. The default for a new task. Hidden from unfiltered lists
open	real work, understood
next	up now
parked	deliberately deferred; the body says why
someday	aspirational
done	finished. Stays in the file for the record. Hidden from unfiltered lists

Tools

• list_todos - abbreviated index; filters area, status, ref, q, limit
• get_todo - full markdown of one task, body included
• add_todo - capture a task; only title required. Reports possible duplicates
• update_todo - change any field; only what is passed is rewritten
• append_note - add a dated bullet to a task's log
• set_status - move a task through triage
• remove_todo - delete a task and its prose. Prefer set_status done

Resources

• todos://list - one-line index of open tasks

Architecture

• src/todo.ts - the markdown store: parsing, byte-range patching, query, dedup
• src/server.ts - MCP tool surface. Pure factory, no side effects on import
• src/http.ts - Streamable HTTP transport, auth and session map
• src/cli.ts - the todo-mcp binary; picks a transport and starts it