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): native tools to list / create / comment / complete tasks, and to shard a ticket into a self-contained BMAD story — so a coding agent can act without re-opening the ticket.
• CLI (bundled): the same operations from your terminal, CI, or cron.

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) by exporting these before launching Claude Code:

export PROOFHUB_ACCOUNT="yourteam"          # "yourteam" or "yourteam.proofhub.com"
export PROOFHUB_API_KEY="your-api-key"      # ProofHub → profile → API access
claude

Run /mcp to confirm the proofhub server is connected. Tools then appear as mcp__proofhub__list_tasks, mcp__proofhub__create_task, mcp__proofhub__shard_to_story, etc.

MCP tools

Tool	Does
proofhub_list_projects	list projects
proofhub_list_todolists	list task lists in a project
proofhub_list_tasks	list tasks in a todolist
proofhub_get_task	full JSON for one task
proofhub_create_task	create a task
proofhub_comment	comment on a task
proofhub_complete	mark a task complete
proofhub_shard_to_story	BMAD: shard a ticket into a self-contained story file

BMAD sharding

proofhub_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 tasks <projectId> <todolistId>
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.

npm test      # no-network self-test

MIT © Yash Mody