# spranab/saga-mcp [Health: Active]

**Category:** 📋 Product Management  
**Repository:** https://github.com/spranab/saga-mcp  
**GitHub Stars:** 40  
**npm Downloads (last month):** 1923  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/spranab-saga-mcp

## Description
A Jira-like project tracker for AI agents with full hierarchy (Projects > Epics > Tasks > Subtasks), task dependencies with auto-block/unblock, threaded comments, reusable templates, activity logging, and a natural language dashboard. SQLite-backed, 31 tools.

## Tools
Capabilities this server exposes over MCP:

- **tracker_init** — Initialize tracker and create first project
- **tracker_next** — What to work on next, with the reason and what is blocked
- **tracker_dashboard** — Full project overview with natural language summary
- **project_create** — Create a new project
- **project_list** — List projects with completion stats
- **project_update** — Update project (archive to soft-delete)
- **epic_create** — Create an epic within a project
- **epic_list** — List epics with task counts
- **epic_update** — Update an epic
- **epic_archive** — Archive/unarchive an epic, hiding it and its tasks from listings
- **task_create** — Create a task with optional dependencies
- **task_list** — List/filter tasks; follows a manual arrangement when one exists
- **task_get** — Get task with subtasks, notes, comments, and dependencies
- **task_update** — Update task (auto-logs, auto-blocks/unblocks)
- **task_batch_update** — Update multiple tasks at once
- **task_reorder** — Set the order of an epic's tasks
- **task_lock_description** — Lock/unlock a description so agents can't rewrite it
- **task_delete** — Remove a `todo` task (soft delete, restorable)
- **task_restore** — Restore a removed task
- **subtask_create** — Create subtask(s) — supports batch
- **subtask_update** — Update title/status/position; `depends_on` and `blocks` set ordering
- **subtask_reorder** — Set the order of a task's subtasks in one call
- **subtask_delete** — Delete subtask(s) — supports batch
- **comment_add** — Add a comment to a task (threaded discussion)
- **comment_list** — List comments on a task (removed ones hidden unless `include_deleted`)
- **comment_delete** — Remove a comment — soft delete, row kept for audit
- **comment_restore** — Restore a removed comment
- **template_create** — Create a reusable task template with `{variable}` placeholders
- **template_list** — List templates; `include_tasks` shows what each one creates
- **template_update** — Edit a template in place — name, description or tasks
- **template_apply** — Apply template to create tasks with variable substitution
- **template_delete** — Delete a template
- **note_save** — Create or update a note (upsert)
- **note_list** — List notes with filters
- **note_search** — Full-text search across notes
- **note_delete** — Delete a note
- **tracker_search** — Cross-entity search (projects, epics, tasks, notes)
- **activity_log** — View change history with filters
- **tracker_session_diff** — What changed since a timestamp — call at session start
- **tracker_export** — Export full project as nested JSON (includes dependencies and comments)
- **tracker_import** — Import project from JSON (matching export format)

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "saga-mcp": {
    "command": "npx",
    "args": ["-y","-p","saga-mcp","saga-web"],
    "env": {
      "DB_PATH": "",
      "SAGA_PROJECT": "",
      "SAGA_DESCRIPTION_LOCK": "",
      "SAGA_TOOLS": ""
    }
  }
}
```

**Requires environment variables:** `DB_PATH`, `SAGA_PROJECT`, `SAGA_DESCRIPTION_LOCK`, `SAGA_TOOLS` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What spranab/saga-mcp MCP server does

spranab/saga-mcp MCP server stores project planning data in a SQLite file that belongs to the user. Its hierarchy runs from projects to epics, tasks, and subtasks, allowing an agent to preserve work plans instead of relying on temporary conversation context.

The tracker supports task dependencies, threaded comments, reusable templates, manual ordering, soft deletion, restoration, archiving, and activity logging. Task updates can record changes and recalculate dependency status. A task description can also be locked to prevent an agent from replacing the original specification with progress notes.

## How it works

The MCP process reads and writes the configured SQLite database. `tracker_init` can create the initial project, while project, epic, task, subtask, comment, and template tools manage the stored records. The database file and schema are created on first use, so no external database service is required.

Dependencies are evaluated when relevant task state changes. A dependent task becomes blocked while prerequisite work is unfinished and can become available again when the prerequisite is completed. Reopening a prerequisite can block its dependents again, and circular task or subtask dependencies are rejected.

`tracker_next` selects a recommended next task and explains the choice, including blocked or overdue work. `tracker_dashboard` returns a broader project view with statistics, epics, blocked and overdue tasks, recent activity, notes, and a natural-language summary. Task lists follow a manually assigned epic order when one exists; otherwise, priority sorting applies unless another sort is requested.

## Setup and configuration

Add the server to an MCP client using `npx -y saga-mcp` and set `DB_PATH` to an absolute path for the SQLite file. The same configuration format is documented for Claude Code and Claude Desktop, and the package can also be installed globally with npm before using `saga-mcp` as the command.

`DB_PATH` is required. `SAGA_PROJECT` optionally scopes tools to a project by ID or name, which is useful when several repositories share one database. `SAGA_DESCRIPTION_LOCK` can enable automatic description locking when work starts. `SAGA_TOOLS` accepts `full` or `core`; the latter exposes a smaller tool set for ordinary tracking sessions.

The README reports testing with Node 20, 22, and 24 on Linux, macOS, and Windows. No API key, account, or network service is required.

## Tools and capabilities

The listed tools cover:

- Creating, listing, updating, archiving, and restoring projects, epics, tasks, and subtasks.
- Adding task dependencies, reordering tasks or subtasks, and applying batch updates or deletions.
- Locking task descriptions and retrieving task details with subtasks, notes, comments, and dependencies.
- Adding, listing, deleting, and restoring threaded task comments.
- Creating, listing, and editing templates with `{variable}` placeholders.
- Checking the next recommended task and viewing a project dashboard.

## Limitations and notes

spranab/saga-mcp is local-file based, so the database path must be available to the MCP process. It does not provide an external hosted service or network synchronization. Archived epics and soft-deleted records are hidden from normal listings, although supported restore operations can recover removed tasks and comments.

_Full upstream README: https://allmcps.com/mcp/spranab-saga-mcp/readme_