spranab/saga-mcp

Your coding agent loses the plan between sessions. You come back tomorrow and it has no idea which
of the five things you agreed on are done, which one is blocked on which, or why you rejected the
second approach — because the plan lived in the context window, or in a TODO.md nobody updates.
saga-mcp gives the agent a real tracker instead: a SQLite file in your project holding projects,
epics, tasks, subtasks, dependencies, comments, notes and decisions, exposed as 41 MCP tools. The
agent writes to it as it works and reads it back when it returns. No accounts, no external service,
no network calls — the database is a file you own.
---
Install
Add saga-mcp to your MCP client. The same block works for Claude Code (.mcp.json in your
project), Claude Desktop (claude_desktop_config.json), and any other MCP client:
Restart the client. DB_PATH is the only required setting; the file and its schema are created on
first use. Prefer a global install? npm install -g saga-mcp, then use saga-mcp as the command
instead of npx.
Tested on Node 20, 22 and 24, on Linux, macOS and Windows.
Settings
| Variable | Required | Description |
|----------|----------|-------------|
| DB_PATH | Yes | Path to the .tracker.db SQLite file. Created on first use. |
| SAGA_PROJECT | No | Scope every tool to one project, by id or name. Set this per repo when several repos share one database. |
| SAGA_DESCRIPTION_LOCK | No | on_progress locks a task's description the moment work starts on it. Off by default. See keeping agents on the rails. |
| SAGA_TOOLS | No | full (default) lists all 41 tools. core lists only the 13 an ordinary tracking session needs, saving ~4,300 tokens per session. See token cost. |
No API keys, no accounts, no external services.
---
Your first session
**You:** "Set up tracking for the e-commerce API and plan out auth."
Tasks 2 and 3 come back **blocked** — their dependencies aren't done. Finish task 1 and task 2
unblocks itself. That whole exchange, actually run against saga-mcp:
**Next session, you:** "Where were we?"
One recommendation with the reason. For the whole picture instead, tracker_dashboard({}) returns
stats, epics, blocked and overdue tasks, recent activity and notes, with a summary on top.
And when you would rather look than ask, saga-web puts the same database in a browser:
---
What you get
- **The next thing to do** — one recommendation with its reason, at a
third the cost of the dashboard
- **Real sequencing** — dependencies that auto-block and auto-unblock,
a manual order the tools respect, and cycles refused rather than deadlocked
- **Guards against agent drift** — a lockable description, and
prerequisites enforced on write rather than merely reported
- **A web UI** — saga-web serves the same database in a browser, read *and* write
- **Templates** — reusable task sets with {variable} substitution, editable in place
- **Archiving and soft delete** — get finished work out of the
context you pay for, reversibly
- **Forgiving input** — a smaller model sending an array as a JSON string
doesn't silently collapse your batch into one record
- **One file, many projects** — per-repo databases or one shared file
- **A full audit trail** — every mutation logged with old and new values, and nothing an agent
removes is unrecoverable
- **41 tools** with MCP safety annotations on every one, and a tiered surface when
you want a smaller context bill
---
Asking what to do next
tracker_dashboard hands an agent everything and leaves it to reason. tracker_next answers the
question:
One recommendation with the reason, the next unfinished subtask inside it, a couple of
alternatives, and anything overdue or blocked. About a third the size of the dashboard.
The ordering rule worth knowing: **continuing beats starting.** A task already in progress outranks
an untouched one that is overdue or higher priority, because abandoning work in flight just leaves
two things unfinished — the overdue work is named in the summary instead. Blocked tasks are never
recommended, archived epics and removed tasks are skipped, and subtask dependencies decide which
step comes next inside the chosen task.
When nothing is actionable it says what to unblock rather than returning an empty answer:
---
Ordering and dependencies
**A deliberate order wins over a guess.** task_list sorts by priority until someone arranges an
epic, and from then on it follows the arrangement:
Priority is a reasonable guess about what matters; a sequence someone wrote down is not a guess.