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 31 MCP tools. The agent writes to it as it works and
reads the dashboard when it comes back. No accounts, no external service, no
network calls — the database is a file you own.

Install (60 seconds)

Claude Code — add to your project's .mcp.json:

{
  "mcpServers": {
    "saga": {
      "command": "npx",
      "args": ["-y", "saga-mcp"],
      "env": { "DB_PATH": "/absolute/path/to/your/project/.tracker.db" }
    }
  }
}

Restart the client. DB_PATH is the only setting; the file and schema are
created on first use.

What it looks like

You: "Set up tracking for the e-commerce API and plan out auth."

tracker_init({ project_name: "E-Commerce API" })
epic_create({ project_id: 1, name: "Authentication", priority: "high" })
task_create({ epic_id: 1, title: "Design auth schema", priority: "critical" })
task_create({ epic_id: 1, title: "Implement JWT auth", depends_on: [1] })
task_create({ epic_id: 1, title: "Add OAuth2 Google login", depends_on: [2] })

Tasks 2 and 3 come back blocked — their dependencies aren't done. Finish
task 1 and task 2 unblocks itself.

Next session, you: "Where were we?"

tracker_dashboard({})
→ "E-Commerce API: 5 tasks across 2 epics. 40% complete.
   Active: Authentication (2/3 done). Next up: Product Catalog (2 tasks).
   1 blocked task(s)."

Plus the structured data behind it: stats, epics, blocked and overdue tasks,
recent activity, notes.

Features

• Full hierarchy: Projects > Epics > Tasks > Subtasks
• Task dependencies: Express sequencing with auto-block/unblock when deps are met
• Comments: Threaded discussions on tasks — leave breadcrumbs across sessions
• Templates: Reusable task sets with {variable} substitution
• Dashboard: One tool call gives full overview with natural language summary
• SQLite: Self-contained .tracker.db file per project — zero setup, no external database
• Activity log: Every mutation is automatically tracked with old/new values
• Notes system: Decisions, context, meeting notes, blockers — all searchable
• Batch operations: Create multiple subtasks or update multiple tasks in one call
• 31 focused tools: With MCP safety annotations on every tool
• Import/export: Full project backup and migration as JSON (with dependencies and comments)
• Source references: Link tasks to specific code locations
• Auto time tracking: Hours computed automatically from activity log
• Cross-platform: Works on macOS, Windows, and Linux

Other clients

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "saga": {
      "command": "npx",
      "args": ["-y", "saga-mcp"],
      "env": {
        "DB_PATH": "/absolute/path/to/your/project/.tracker.db"
      }
    }
  }
}

With Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "saga": {
      "command": "npx",
      "args": ["-y", "saga-mcp"],
      "env": {
        "DB_PATH": "/absolute/path/to/your/project/.tracker.db"
      }
    }
  }
}

Manual install

npm install -g saga-mcp
DB_PATH=./my-project/.tracker.db saga-mcp

Configuration

saga-mcp requires a single environment variable:

No API keys, no accounts, no external services. Everything is stored locally in the SQLite file you specify.

Tools

Getting Started

Projects

Epics

Tasks

Subtasks

Comments

Templates

Notes

Intelligence

Import / Export

Usage Examples

Example 1: Starting a project with dependencies

User prompt: "Set up tracking for my new e-commerce API project"

Tool calls:

tracker_init({ project_name: "E-Commerce API", project_description: "REST API for online store" })
epic_create({ project_id: 1, name: "Authentication", priority: "high" })
task_create({ epic_id: 1, title: "Design auth schema", priority: "critical" })
task_create({ epic_id: 1, title: "Implement JWT auth", priority: "high", depends_on: [1] })
task_create({ epic_id: 1, title: "Add OAuth2 Google login", priority: "medium", depends_on: [2] })

Result: Task 2 and 3 are auto-blocked because their dependencies aren't done yet. When task 1 is marked done, task 2 auto-unblocks.

Example 2: Resuming work with dashboard summary

Tool calls:

tracker_dashboard({})

Response includes a natural language summary:

"E-Commerce API: 5 tasks across 2 epics. 40% complete. Active: Authentication (2/3 done). Next up: Product Catalog (2 tasks). 1 blocked task(s)."

Plus the full structured data (stats, epics, blocked tasks, overdue tasks, activity, notes).

Example 3: Using templates for repeated workflows

Create a template:

template_create({
  name: "feature_workflow",
  description: "Standard feature implementation",
  tasks: [
    { "title": "Design {feature} API", "priority": "critical", "estimated_hours": 2 },
    { "title": "Implement {feature}", "priority": "high", "estimated_hours": 8 },
    { "title": "Write tests for {feature}", "priority": "high", "estimated_hours": 4 },
    { "title": "Document {feature}", "priority": "medium", "estimated_hours": 1 }
  ]
})

Apply it:

template_apply({ template_id: 1, epic_id: 2, variables: { "feature": "user auth" } })

Creates 4 tasks: "Design user auth API", "Implement user auth", "Write tests for user auth", "Document user auth".

Example 4: Task comments as decision trail

comment_add({ task_id: 5, content: "Investigated root cause: CORS headers missing on preflight" })
comment_add({ task_id: 5, content: "Fixed by adding OPTIONS handler. Tested with curl." })
task_update({ id: 5, status: "done" })

Comments persist across sessions — next time an agent calls task_get(5), it sees the full discussion thread.

How It Works

saga-mcp stores everything in a single SQLite file (.tracker.db) per project. The database is auto-created on first use with all tables and indexes — no migration step needed.

Hierarchy

Project
  └── Epic (feature/workstream)
        └── Task (unit of work)
              ├── Subtask (checklist item)
              ├── Comment (discussion thread)
              └── Dependencies (blocked by other tasks)

Task Dependencies

Tasks can depend on other tasks. When you set depends_on: [2, 3] on a task:

• The task is auto-blocked if any dependency isn't done
• When a dependency is marked done, downstream tasks are re-evaluated
• If all dependencies are met, the blocked task auto-unblocks to todo

Note Types

Notes replace scattered markdown files. Each note has a type:

Activity Log

Every create, update, and delete is automatically recorded:

{
  "summary": "Task 'Fix CORS issue' status: blocked -> done",
  "action": "status_changed",
  "entity_type": "task",
  "entity_id": 15,
  "field_name": "status",
  "old_value": "blocked",
  "new_value": "done",
  "created_at": "2026-02-21T18:30:00"
}

Privacy Policy

saga-mcp is a fully local, offline tool. It does not:

• Collect any user data
• Send any data to external servers
• Require internet access after installation
• Use analytics, telemetry, or tracking of any kind

All data is stored exclusively in the local SQLite file specified by DB_PATH. You own your data completely. Uninstalling saga-mcp and deleting the .tracker.db file removes all traces.

For questions about privacy, open an issue at https://github.com/spranab/saga-mcp/issues.

Development

git clone https://github.com/spranab/saga-mcp.git
cd saga-mcp
npm install
npm run build
DB_PATH=./test.db npm start

Support

• Issues: https://github.com/spranab/saga-mcp/issues
• Repository: https://github.com/spranab/saga-mcp

Related projects

Part of a set of agent infrastructure built by one person, meant to be used
together:

• yantrikdb-mcp — persistent
  cognitive memory for the same agent: what it learned, not what it planned.
• brainstorm-mcp — multi-model
  debate before you commit a plan to the tracker.
• swarmcode — real-time channel
  between Claude Code instances on different machines.
• truenas-mcp — 278 TrueNAS SCALE
  actions behind one hierarchical tool.
• mcpier — self-hosted MCP control plane
  that keeps API keys off your clients.

License

MIT