@outputty/tasks-mcp

A dependency-aware task tracker for coding agents: an MCP server, a CLI, and a library over one task graph that is mirrored two-way into GitHub — one issue per task, field:value labels for its execution properties, and a Projects v2 kanban board.

The graph holds two altitudes. Tasks are units of work with dependencies, scope, and a build brief. Targets are roadmap rows that group them, and their progress is counted from the tasks rather than typed by anyone. list_ready answers what can be worked right now, ranked at both altitudes.

Requirements

• Node 18 or newer.
• A git repository with a github.com origin remote.
• A GitHub token: GITHUB_TOKEN, GH_TOKEN, or a logged-in gh CLI. For the kanban board, grant the project scope once with gh auth refresh -s project; without it tasks still land as issues.

Install

Nothing to clone. Register the server in your project's .mcp.json and your MCP client launches it on demand:

{
  "mcpServers": {
    "tasks": {
      "command": "npx",
      "args": ["-y", "@outputty/tasks-mcp", "--sync-interval", "60"]
    }
  }
}

Or drive the same graph from a shell:

npm install -g @outputty/tasks-mcp

First run

From inside the repository you want to track:

$ tasks-mcp add order-schema --title "Give an order a stable export shape" --scope src/orders
{
  "id": "order-schema",
  "title": "Give an order a stable export shape",
  "status": "open",
  "deps": [],
  "scope": [
    "src/orders"
  ]
}

That wrote the task to a local cache and opened a GitHub issue for it. Ask what can be worked:

$ tasks-mcp ready
[
  "order-schema"
]

Documentation

Tutorial — start here

• Your first task graph — build a target and two tasks in a throwaway repository, and watch the queue move.

How-to guides

• Register the server with an MCP client — stdio, .mcp.json, credentials, and how to check it before blaming the client.
• Run the server over HTTP — one shared long-running instance instead of a process per client.
• Adopt an existing GitHub Issues backlog — what the first sync writes, and how to give adopted issues structure.
• Recover work from a dead worker — find a stale claim and hand the task back to the queue.
• Change what the queue offers next — priority at both altitudes, dependencies, and lanes for parallel workers.
• Use tasks-mcp as a library — the graph engine, the service, and running without GitHub.
• Develop, test, and release this package — for contributors.

Reference

• MCP tools — all twenty tools, their arguments, and their results.
• CLI — every subcommand, flag, and printed shape.
• Task record — the fields, their defaults, and where each one lives on GitHub.
• Configuration — the settings, the four layers, the files, and the credentials.

Explanation

• The two altitudes — why targets and tasks share one graph.
• Claims — why a claim that has gone quiet is reported and never freed.
• The provider stack — layers, sync rules, and why the store is GitHub Issues.
• Trails — why a task's decision record is its issue comment thread.

License

MIT