# saga-mcp

Keeps an agent's plan in a SQLite file inside your project: epics, subtasks, dependencies and notes. The plan survives between sessions.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 40
- Author: spranab
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/spranab/saga-mcp
- Updated: 2026-10-07
- HTML: https://affpapa.org/en/nevibecode/mcp/saga-mcp

## What it does

A coding agent drops the plan when the session ends. What you agreed on yesterday is gone, along with which item blocked which and why an approach was rejected. saga-mcp replaces the context window and the stale `TODO.md` with a database file in the repo, holding projects, epics, tasks, subtasks, dependencies, comments, notes and decisions. The agent gets 41 MCP tools over it, writes as it works and reads back on return. No accounts, no external service, no network calls.

\`DB_PATH` is the only setting you must provide; it points at the `.tracker.db` file, and both file and schema appear on first use. Optional variables do the rest: `SAGA_PROJECT` scopes every tool to one project, `SAGA_DESCRIPTION_LOCK` set to `on_progress` freezes a task's description once work begins, and `SAGA_TOOLS` set to `core` exposes 13 tools instead of 41, saving roughly 4,300 tokens per session.

Dependencies enforce themselves. A task whose dependency is open comes back blocked and clears when the earlier one finishes, and the server refuses cycles instead of deadlocking. `tracker_next` returns a single recommendation with its reason; `tracker_dashboard` returns stats, blocked and overdue work, recent activity and notes. Tested on Node 20, 22 and 24 across Linux, macOS and Windows.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add saga-mcp -- npx -y saga-mcp
```

### Codex

**Platform CLI**
```bash
codex mcp add saga-mcp -- npx -y saga-mcp
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "saga-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "saga-mcp"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "saga-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "saga-mcp"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add saga-mcp npx -y saga-mcp
```

## When to use it
- recover an agent's plan after a session restart
- chain tasks by dependency so blocked work stays unstarted
- get one next-step recommendation with a stated reason
- move finished work out of the paid context reversibly
- browse the same database in a browser with `saga-web`

## Example prompts
- Where were we?
- Show me the dashboard for this project.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md