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

Tools

Getting Started

Projects

Epics

Tasks

Subtasks

Comments

Templates

Notes

Intelligence

Import / Export

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

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:

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

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.

License

MIT