claude-todo

A lightweight MCP server that gives Claude Code a persistent todo list. Todos are stored in SQLite (built-in node:sqlite, WAL mode), so they survive restarts and are safe to use from several Claude sessions at once.

Requirements

• Node.js >= 22.13

Related MCP server: Notion MCP Integration

Setup

npm install

Register it in .mcp.json (project) or ~/.claude/.mcp.json (user):

{
  "mcpServers": {
    "todo": {
      "command": "node",
      "args": ["/absolute/path/to/claude-todo/src/index.js"]
    }
  }
}

Tools

Actions return a one-line confirmation and don't echo the todo back. When todo_add or todo_update was given a date, a second line Date: <resolved> follows, since inputs like +3d or tomorrow 09:30 are resolved by the server.

todo_list and todo_search return Markdown. Each todo is a section with the checkbox and slug in the heading, one meta item per line, then the prompt as the body:

# Todos (2 open, 3 total)

## [ ] iiot-examen-pratique-1
Importance: high
Date: 2026-09-28 08:10

Study chapters 3-5.
Redo the Modbus lab.

## [ ] write-docs
Importance: medium
Date: 2026-10-01

Write the README.

## [x] old-task
Importance: low
Date: none

Old thing

• [ ] open, [x] done.

• Date is YYYY-MM-DD for all-day todos, local YYYY-MM-DD HH:MM for timed ones, or none.

• The heading counts cover everything matched; , showing N is appended when limit cut the results.

Errors return isError: true with Error <CODE>: <message>, where CODE is one of NOT_FOUND, SLUG_EXISTS, INVALID_DATE, INVALID_INPUT.

Behavior

• Preview: todo_preview is the cheap look-ahead. It prints one line per dated todo (- [ ] slug — date, importance — first line of the prompt, cut at 80 chars) and never the body. today and week include overdue todos; tomorrow and next_week (next Monday–Sunday) are exact windows; upcoming is everything dated and not yet due.

• Ordering: by date (undated last), then importance (high first), then creation time.

• Ranges: day = due today or earlier, week = due by the end of this week (Monday–Sunday) or earlier. Overdue todos are always included; undated todos only appear with any.

• Dates: input without a timezone is taken in the local machine timezone.

  • All-day: today, tomorrow, YYYY-MM-DD

  • Timed: HH:MM[:SS] (today), today 14:00, tomorrow 09:30, YYYY-MM-DD HH:MM[:SS], YYYY-MM-DDTHH:MM[:SS]

  • Relative: +30m, +2h, +1d, +1w

  • ISO 8601 with Z or an offset keeps its own zone; it is stored converted to local time.

• Slugs: unique among open todos. Adding a slug that belongs to a done todo replaces it. Slugs cannot be changed after creation.

• Updates: only the fields passed change. Done todos can be updated too and stay done.

• Search: case-insensitive substring match on slug and prompt.

Configuration