proofhub-mcp

ProofHub for Claude Code — a zero-dependency MCP server (and a CLI) over the ProofHub v3 API, with a BMAD ticket-to-story sharder. Bring your own key; nothing about your account ships in the package.

• MCP server (primary): 16 native tools to list / create / comment / complete tasks, advance tasks through board stages, and shard tickets into self-contained BMAD stories.

• Context: set a project + todolist once — skip the IDs for every subsequent call.

• CLI (bundled): the same operations from your terminal, CI, or cron.

• Slash commands (bundled): /proofhub:setup (guided config + verify) and /proofhub:help (tools + context workflow).

Install as a Claude Code plugin

/plugin marketplace add yashmody/proofhub-mcp
/plugin install proofhub@proofhub-mcp

Then provide your key (bring-your-own-key). The fastest path is the guided command — run /proofhub:setup and it will configure and verify for you. To do it by hand:

Recommended — .claude/settings.local.json (launch-independent). Add an env block to the project's gitignored .claude/settings.local.json, then fully restart Claude Code:

{
  "env": {
    "PROOFHUB_ACCOUNT": "yourteam",
    "PROOFHUB_API_KEY": "your-api-key"
  }
}

⚠️ A shell export in ~/.zshrc works only when you launch Claude Code from a terminal. Started from the macOS Dock/Finder, Claude Code doesn't source your shell, so the .mcp.json placeholder ${PROOFHUB_API_KEY} resolves empty and ProofHub returns WRONG ACCESS TOKEN (code 1001). The settings.local.json env block avoids that. .claude/settings.json is committed — never put the key there.

Alternatives:

# Config file — any terminal, persists at ~/.config/proofhub/config.json (chmod 600)
proofhub login --account yourteam --key your-api-key

# Shell env — only if you always launch Claude Code from a terminal
export PROOFHUB_ACCOUNT="yourteam" PROOFHUB_API_KEY="your-api-key" && claude

Run /mcp to confirm the proofhub server is connected (or proofhub doctor from a terminal). Tools then appear as mcp__proofhub__list_tasks, mcp__proofhub__create_task, mcp__proofhub__shard_to_story, etc. Stuck? /proofhub:setup diagnoses and fixes it.

Related MCP server: Follow Plan MCP Server

Context + stages

Set a current project and list once so you don't have to repeat IDs:

/proofhub use 9654620832
/proofhub use-list 271191425865
/proofhub status          # confirm saved context
/proofhub add "QA smoke"  # no IDs needed
/proofhub find "QA"       # search across lists
/proofhub next 293931     # advance one stage automatically
/proofhub stage 293931 Review  # move to a named stage
/proofhub move 293931 --to-list 99887766

Stages are discovered automatically by scanning tasks — no API endpoint lists them. The order defaults to stage-id ascending (best-effort board order). Override with:

/proofhub stages --set "Backlog,In Progress,Review,Done"

Or via the MCP tool: set_context with stageOrder: "Backlog,In Progress,Review,Done".

MCP tools (16)

All task-scoped tools accept project and todolist as optional overrides; they default to saved context. required is [] on those tools.

Environment overrides

BMAD sharding

shard_to_story turns a ProofHub ticket into a story with Context / Acceptance Criteria / Dev Notes / Tasks-Subtasks and a suggested owner role + model tier — BMAD's core move of embedding full context so the dev agent isn't guessing. See templates/story.md.

CLI (bundled)

export PROOFHUB_ACCOUNT=... PROOFHUB_API_KEY=...
npx -p proofhub-mcp proofhub projects          # or, installed: proofhub projects
proofhub use <projectId>
proofhub use-list <todolistId>
proofhub add "My task"
proofhub find "keyword"
proofhub next <ticket>
proofhub stage <ticket> "Review"
proofhub move <ticket> --to-list <id>
proofhub done <ticket>
proofhub comment <projectId> <todolistId> <ticket> --body "..."

Notes

• Auth header is X-API-KEY (not Bearer); a User-Agent is set automatically. The client throttles to ~25 req/10s and honours Retry-After.

• ProofHub returns some errors as HTTP 200 with a {code,message} envelope — the client surfaces those as errors. Mutations resolve the internal task id from the ticket number automatically.

• In-list stage changes use a plain { stage } PUT. A cross-list move uses move_task: true and must include project — ProofHub returns a {code:1301} "Invalid request" without it.

npm test      # no-network self-test

MIT © Yash Mody