saga-mcp

A Jira-like project tracker MCP server for AI agents. SQLite-backed, per-project scoped, with full hierarchy and activity logging — so LLMs never lose track.

No more scattered markdown files. saga-mcp gives your AI assistant a structured database to track projects, epics, tasks, subtasks, notes, and decisions across sessions.

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

Quick Start

With 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:

Variable	Required	Description
DB_PATH	Yes	Absolute path to the .tracker.db SQLite file. The file and schema are auto-created on first use.

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

Tools

Getting Started

Tool	Description	Annotations
tracker_init	Initialize tracker and create first project	readOnly: false, idempotent: true
tracker_dashboard	Full project overview with natural language summary	readOnly: true

Projects

Tool	Description	Annotations
project_create	Create a new project	readOnly: false
project_list	List projects with completion stats	readOnly: true
project_update	Update project (archive to soft-delete)	readOnly: false, idempotent: true

Epics

Tool	Description	Annotations
epic_create	Create an epic within a project	readOnly: false
epic_list	List epics with task counts	readOnly: true
epic_update	Update an epic	readOnly: false, idempotent: true

Tasks

Tool	Description	Annotations
task_create	Create a task with optional dependencies	readOnly: false
task_list	List/filter tasks with dependency info	readOnly: true
task_get	Get task with subtasks, notes, comments, and dependencies	readOnly: true
task_update	Update task (auto-logs, auto-blocks/unblocks)	readOnly: false, idempotent: true
task_batch_update	Update multiple tasks at once	readOnly: false, idempotent: true

Subtasks

Tool	Description	Annotations
subtask_create	Create subtask(s) — supports batch	readOnly: false
subtask_update	Update subtask title/status	readOnly: false, idempotent: true
subtask_delete	Delete subtask(s) — supports batch	destructive: true, idempotent: true

Comments

Tool	Description	Annotations
comment_add	Add a comment to a task (threaded discussion)	readOnly: false
comment_list	List all comments on a task	readOnly: true

Templates

Tool	Description	Annotations
template_create	Create a reusable task template with {variable} placeholders	readOnly: false
template_list	List available templates	readOnly: true
template_apply	Apply template to create tasks with variable substitution	readOnly: false
template_delete	Delete a template	destructive: true, idempotent: true

Notes

Tool	Description	Annotations
note_save	Create or update a note (upsert)	readOnly: false
note_list	List notes with filters	readOnly: true
note_search	Full-text search across notes	readOnly: true
note_delete	Delete a note	destructive: true, idempotent: true

Intelligence

Tool	Description	Annotations
tracker_search	Cross-entity search (projects, epics, tasks, notes)	readOnly: true
activity_log	View change history with filters	readOnly: true
tracker_session_diff	Show what changed since a given timestamp — call at session start	readOnly: true

Import / Export

Tool	Description	Annotations
tracker_export	Export full project as nested JSON (includes dependencies and comments)	readOnly: true
tracker_import	Import project from JSON (matching export format)	readOnly: false

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:

Type	Use case
general	Free-form notes
decision	Architecture/design decisions
context	Conversation context for future sessions
meeting	Meeting notes
technical	Technical details, specs
blocker	Blockers and issues
progress	Progress updates
release	Release notes

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

License

MIT