saga-mcp — Claude Code MCP server: task tracker for agents
Keeps an agent's plan in a SQLite file inside your project: epics, subtasks, dependencies and notes. The plan survives between sessions.
claude mcp add saga-mcp -- npx -y saga-mcpWhat saga-mcp does
A coding agent drops the plan when the session ends. What you agreed on yesterday is gone, along with which item blocked which and why an approach was rejected. saga-mcp replaces the context window and the stale TODO.md with a database file in the repo, holding projects, epics, tasks, subtasks, dependencies, comments, notes and decisions. The agent gets 41 MCP tools over it, writes as it works and reads back on return. No accounts, no external service, no network calls.
DB_PATH is the only setting you must provide; it points at the .tracker.db file, and both file and schema appear on first use. Optional variables do the rest: SAGA_PROJECT scopes every tool to one project, SAGA_DESCRIPTION_LOCK set to on_progress freezes a task's description once work begins, and SAGA_TOOLS set to core exposes 13 tools instead of 41, saving roughly 4,300 tokens per session.
Dependencies enforce themselves. A task whose dependency is open comes back blocked and clears when the earlier one finishes, and the server refuses cycles instead of deadlocking. tracker_next returns a single recommendation with its reason; tracker_dashboard returns stats, blocked and overdue work, recent activity and notes. Tested on Node 20, 22 and 24 across Linux, macOS and Windows.
What it helps with
- recover an agent's plan after a session restart
- chain tasks by dependency so blocked work stays unstarted
- get one next-step recommendation with a stated reason
- move finished work out of the paid context reversibly
- browse the same database in a browser with
saga-web
Example prompts for the agent
- Where were we?
- Show me the dashboard for this project.
How to install saga-mcp
Platform CLI
claude mcp add saga-mcp -- npx -y saga-mcpPlatform CLI
codex mcp add saga-mcp -- npx -y saga-mcpConfig file
{
"mcpServers": {
"saga-mcp": {
"command": "npx",
"args": [
"-y",
"saga-mcp"
]
}
}
}Config file
{
"servers": {
"saga-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"saga-mcp"
]
}
}
}Platform CLI
gemini mcp add saga-mcp npx -y saga-mcpStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about saga-mcp
How do I install saga-mcp in Claude Code?
Run claude mcp add saga-mcp -- npx -y saga-mcp and restart the client. The same command and args block works in other MCP clients.
What does saga-mcp do?
It stores projects, epics, tasks, subtasks, dependencies, comments and decisions in a SQLite file inside your project and exposes them to the agent as 41 MCP tools. The agent writes while it works and reads back next session.
Does it need API keys or an external service?
No. The database is a file you own and the server makes no network calls. DB_PATH is the only required setting.
