toban-mcp

Cross-project task management MCP server for AI coding agents.

One SQLite database gives all your Claude Code sessions a shared backlog — plus structured decision records for the choices that don't belong in Git.

Install

Add to your Claude Code MCP config (~/.claude/.mcp.json or .mcp.json):

{
  "mcpServers": {
    "toban": {
      "command": "npx",
      "args": ["toban-mcp"]
    }
  }
}

Or install globally:

npm install -g toban-mcp

Data is stored at ~/.toban/backlog.db (override with TOBAN_DB_PATH).

Tools

Tasks

| Tool | Description | |---|---| | create_task | Create a task with title, priority, project, labels | | list_tasks | List tasks with filters (status, priority, project, label, all_projects) | | update_task | Update status, priority, commit_hash, labels, etc. | | search_tasks | Search tasks by keyword |

Decisions

| Tool | Description | |---|---| | record_decision | Record a design decision (title, context, decision, reason, tags) | | list_decisions | List recent decisions by project | | search_decisions | Search decisions by keyword or tag |

Codebase

| Tool | Description | |---|---| | get_codebase_structure | Scan file structure with exported symbols from TS/JS files |

Usage

Session Start (recommended in CLAUDE.md)

## Task Management (Toban)
- Session start: check `list_tasks(all_projects=true, status="todo")` and `list_tasks(all_projects=true, status="in_progress")`
- Starting work: `update_task(id, status="in_progress")`
- Completing work: `update_task(id, status="done", commit_hash="<hash>")`
- New work: `create_task(title, project, priority, labels)`
- Design choices: `record_decision(title, context, decision, reason, project, tags)`

Hooks (recommended)

Auto-check tasks on session start (~/.claude/settings.json):

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [{
          "type": "command",
          "command": "echo '[Task Check] Session started. Use list_tasks(all_projects=true, status=todo/in_progress) to review pending tasks. Work should be tied to tasks — create one with create_task if none exists. Set in_progress when starting, done when completing.'"
        }]
      }
    ]
  }
}

Manager Agent

A dedicated session can act as a read-only overview across all projects:

## Manager CLAUDE.md
- `list_tasks(all_projects=true, status="in_progress")` — check progress across all projects
- `list_decisions(all_projects=true)` — review recent design decisions
- `search_decisions(query="keyword")` — search past decisions
- Task creation and status changes are done by worker agents, not the manager

Labels

Classify tasks with labels:

create_task(title="Add auth", labels="feature,security")
list_tasks(label="bug")

Commit Hash

Trace completed work back to commits:

update_task(id="abc123", status="done", commit_hash="a1b2c3d4")

Environment Variables

| Variable | Default | Description | |---|---|---| | TOBAN_DB_PATH | ~/.toban/backlog.db | SQLite database path | | TOBAN_PROJECT | Current directory name | Default project name |

Architecture

Claude Code Session A (project-a/)  ──┐
Claude Code Session B (project-b/)  ──┼── toban-mcp ── ~/.toban/backlog.db
Claude Code Session C (project-c/)  ──┤
Manager Session (~/workspace/)      ──┘

• Each session runs toban-mcp independently
• Shared SQLite (WAL mode) unifies data across all sessions
• No direct inter-agent communication (by design)
• Human orchestrates across sessions

Development

npm install
npm run build    # TypeScript compile
npm test         # Run tests
npm run dev      # Run with tsx (dev mode)

License

MIT