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

Saga