ProofHub MCP Server
yashmody/proofhub-mcp
Integração ProofHub + Claude Code com gestão de tarefas e ticket-to-story
Ver no GitHubServidor MCP que integra ProofHub com Claude Code, oferecendo 16 ferramentas nativas para gerenciar tarefas, projetos e listas de afazeres. Inclui um sharder BMAD para quebrar tickets em histórias independentes e uma CLI bundled para terminal, CI e cron jobs.
Instalação
npx convez-ai yashmody/proofhub-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Gerenciar projetos e tarefas do ProofHub direto no Claude Code
- Automatizar criação, conclusão e movimentação de tickets entre estágios
- Converter tickets complexos em histórias de desenvolvimento estruturadas (BMAD)
- Executar operações ProofHub via CLI, CI/CD ou cron jobs
Veredito

Integração sólida e pronta para produção que conecta ProofHub ao Claude Code com zero dependências externas. Útil para equipes que já usam ProofHub, mas requer credenciais próprias (bring-your-own-key) e configuração inicial.
README
A tradução para o português deste README ainda está na fila.
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
exportin~/.zshrcworks 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.jsonplaceholder${PROOFHUB_API_KEY}resolves empty and ProofHub returns WRONG ACCESS TOKEN (code 1001). Thesettings.local.jsonenv block avoids that..claude/settings.jsonis 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.
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)
| Tool | Does |
|---|---|
set_context | save project / todolist / stageOrder as context |
get_context | show current context |
list_projects | list projects |
list_todolists | list task lists (defaults to context) |
list_tasks | list tasks in a todolist (defaults to context) |
get_task | full JSON for one task (defaults to context) |
create_task | create a task (defaults to context) |
comment | comment on a task (defaults to context) |
complete | mark a task complete (defaults to context) |
reopen | reopen (un-complete) a task (defaults to context) |
find_task | search tasks by title across all lists (defaults to context) |
list_stages | discover board stages in id-ascending order (defaults to context) |
set_stage | move task to a specific stage by name or id (defaults to context) |
next_stage | advance task one stage forward automatically (defaults to context) |
move_task | move task to another list / project (defaults to context) |
shard_to_story | BMAD: shard a ticket into a self-contained story file |
All task-scoped tools accept project and todolist as optional overrides; they default to
saved context. required is [] on those tools.
Environment overrides
| Variable | Purpose |
|---|---|
PROOFHUB_ACCOUNT | ProofHub subdomain or full hostname |
PROOFHUB_API_KEY | API key |
PROOFHUB_PROJECT | Override saved context project (highest priority) |
PROOFHUB_TODOLIST | Override saved context todolist (highest priority) |
PROOFHUB_STATE_PATH | Override context state file path (default ~/.config/proofhub/state.json) |
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); aUser-Agentis set automatically. The client throttles to ~25 req/10s and honoursRetry-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 usesmove_task: trueand must includeproject— ProofHub returns a{code:1301}"Invalid request" without it.
npm test # no-network self-test
MIT © Yash Mody