README.md
A Jira-like project tracker MCP server for AI agents.
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.dbfile 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 |
Tools (21)
tracker_initInitialize tracker and create first projecttracker_dashboardFull project overview with natural language summaryproject_createCreate a new projectproject_listList projects with completion statsproject_updateUpdate project (archive to soft-delete)epic_createCreate an epic within a projectepic_listList epics with task countsepic_updateUpdate an epictask_createCreate a task with optional dependenciestask_listList/filter tasks with dependency infotask_getGet task with subtasks, notes, comments, and dependenciestask_updateUpdate task (auto-logs, auto-blocks/unblocks)task_batch_updateUpdate multiple tasks at oncesubtask_createCreate subtask(s) — supports batchsubtask_updateUpdate subtask title/statussubtask_deleteDelete subtask(s) — supports batchcomment_addAdd a comment to a task (threaded discussion)comment_listList all comments on a tasktemplate_createCreate a reusable task template with {variable} placeholderstemplate_listList available templatestemplate_applyApply template to create tasks with variable substitutionEnvironment Variables
DB_PATHrequiredAbsolute path to the .tracker.db SQLite file.Configuration
claude_desktop_config.json
{"mcpServers": {"saga": {"command": "npx", "args": ["-y", "saga-mcp"], "env": {"DB_PATH": "/absolute/path/to/your/project/.tracker.db"}}}}Try it
→Initialize a new project tracker for my current development project.
→Show me the project dashboard and summarize the current blockers.
→Create a new epic for the authentication module and add three subtasks.
→List all tasks that are currently blocked by other dependencies.
→Add a comment to the database migration task noting that we need to wait for the API update.