convez.ai
MCP ServerIntegração & APIsIntermediário
yashmody

ProofHub MCP Server

yashmody/proofhub-mcp

Integração ProofHub + Claude Code com gestão de tarefas e ticket-to-story

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor 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-mcp

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.4.1
Issues abertas
1
Contribuidores
1

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 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.

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)

ToolDoes
set_contextsave project / todolist / stageOrder as context
get_contextshow current context
list_projectslist projects
list_todolistslist task lists (defaults to context)
list_taskslist tasks in a todolist (defaults to context)
get_taskfull JSON for one task (defaults to context)
create_taskcreate a task (defaults to context)
commentcomment on a task (defaults to context)
completemark a task complete (defaults to context)
reopenreopen (un-complete) a task (defaults to context)
find_tasksearch tasks by title across all lists (defaults to context)
list_stagesdiscover board stages in id-ascending order (defaults to context)
set_stagemove task to a specific stage by name or id (defaults to context)
next_stageadvance task one stage forward automatically (defaults to context)
move_taskmove task to another list / project (defaults to context)
shard_to_storyBMAD: 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

VariablePurpose
PROOFHUB_ACCOUNTProofHub subdomain or full hostname
PROOFHUB_API_KEYAPI key
PROOFHUB_PROJECTOverride saved context project (highest priority)
PROOFHUB_TODOLISTOverride saved context todolist (highest priority)
PROOFHUB_STATE_PATHOverride 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); 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

Ver o original no GitHub

Bom para

Relacionados