ZenHub

Acesse a API GraphQL do ZenHub para gerenciar fluxos de trabalho de projetos e aumentar a produtividade.

GitHub
1
Experimente este MCPPatrocinado

Documentação

Servidor MCP ZenHub

Um servidor MCP (Model Context Protocol) que fornece acesso completo à API GraphQL do ZenHub.

Recursos

  • Acesso GraphQL Completo: Execute qualquer consulta GraphQL contra a API do ZenHub
  • Operações Comuns: Ferramentas integradas para tarefas frequentes como criar issues, épicos, workspaces e sprints
  • Autenticação Segura: Autenticação baseada em chave de API para todas as solicitações
  • Tratamento de Erros: Tratamento e validação abrangentes de erros

Instalação

Para Desenvolvimento

npm install
npm run build

Configurar Chave de API

  1. Obtenha sua chave de API do ZenHub em Configurações do ZenHub

  2. Defina a variável de ambiente:

export ZENHUB_API_KEY=your_api_key_here

Ou crie um arquivo .env (copie de .env.example):

cp .env.example .env
# Edit .env and add your API key

Para Claude Desktop

  1. Compile o servidor:
npm install
npm run build
  1. Adicione à configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS):
{
  "mcpServers": {
    "zenhub": {
      "command": "npx",
      "args": ["zenhub-mcp-server"],
      "env": {
        "ZENHUB_API_KEY": "your_api_key_here"
      }
    }
  }
}

Para Cursor

  1. Compile o servidor:
npm install
npm run build
  1. No Cursor, vá para Configurações > Servidores MCP e adicione:
{
  "name": "zenhub",
  "command": "node",
  "args": ["/path/to/zenhub-mcp/dist/index.js"],
  "env": {
    "ZENHUB_API_KEY": "zh_",
    "GITHUB_PAT": "github_pat_"
  }
}

Ou use o servidor de desenvolvimento:

{
  "name": "zenhub-dev",
  "command": "npm",
  "args": ["run", "dev"],
  "cwd": "/path/to/zenhub-mcp",
  "env": {
    "ZENHUB_API_KEY": "your_api_key_here"
  }
}

Ferramentas

O servidor fornece 54 ferramentas em 10 categorias, implementando as operações mais comuns do ZenHub:

Nenhuma chave de API necessária nas chamadas de ferramenta - Defina a variável de ambiente ZENHUB_API_KEY uma vez e use todas as ferramentas!

Ferramentas de Consulta (7 ferramentas)

zenhub_query

Execute qualquer consulta GraphQL contra a API do ZenHub.

  • query (obrigatório): String de consulta GraphQL
  • variables (opcional): Variáveis para a consulta

zenhub_search_issues

Pesquise issues em um pipeline.

  • pipeline_id (obrigatório): ID do pipeline para pesquisar
  • query (opcional): Consulta de pesquisa para o título
  • filters (opcional): Objeto com filtros para labels e responsáveis

zenhub_search_issues_in_repository

Pesquise e filtre issues dentro do repositório.

  • repository_id (obrigatório): ID do repositório para pesquisar
  • query (opcional): Consulta de pesquisa
  • filters (opcional): Opções de filtro

zenhub_get_workspace_issues

Obtenha todas as issues em um workspace (paginado).

  • workspace_id (obrigatório): ID do workspace
  • after (opcional): Cursor para paginação

zenhub_get_viewer

Obtenha informações do usuário atual do ZenHub.

zenhub_get_issue_by_info

Consulte uma issue por repositório e número da issue.

  • repository_gh_id (obrigatório): ID do repositório GitHub
  • issue_number (obrigatório): Número da issue

zenhub_get_repositories

Consulte repositórios pelos seus IDs do GitHub.

  • repository_gh_ids (obrigatório): Matriz de IDs de repositórios GitHub

Gerenciamento de Issues (13 ferramentas)

zenhub_create_issue

Crie uma nova issue no GitHub via ZenHub.

  • title (obrigatório): Título da issue
  • repository_id (obrigatório): ID do repositório
  • body (opcional): Descrição da issue
  • labels (opcional): Matriz de nomes de labels
  • assignees (opcional): Matriz de nomes de usuários GitHub

zenhub_close_issues

Feche uma ou mais issues.

  • issue_ids (obrigatório): Matriz de IDs de issues

zenhub_reopen_issues

Reabra uma ou mais issues fechadas.

  • issue_ids (obrigatório): Matriz de IDs de issues
  • pipeline_id (obrigatório): ID do pipeline para mover as issues
  • position (opcional): Posição no pipeline (START ou END)

zenhub_move_issue

Mova issues para uma posição em um pipeline.

  • issue_ids (obrigatório): Matriz de IDs de issues
  • pipeline_id (obrigatório): ID do pipeline para mover as issues
  • position (opcional): Posição no pipeline (baseado em 0)

zenhub_add_assignees_to_issues

Adicione responsáveis a múltiplas issues.

  • issue_ids (obrigatório): Matriz de IDs de issues
  • assignees (obrigatório): Matriz de nomes de usuários GitHub

zenhub_add_labels_to_issues

Adicione labels a múltiplas issues.

  • issue_ids (obrigatório): Matriz de IDs de issues
  • labels (obrigatório): Matriz de nomes de labels

zenhub_set_estimate

Defina uma estimativa para uma issue.

  • issue_id (obrigatório): ID da issue
  • value (obrigatório): Valor da estimativa

zenhub_set_multiple_estimates

Defina estimativas em múltiplas issues.

  • estimates (obrigatório): Matriz de pares de ID de issue e valor de estimativa

zenhub_add_issues_to_epics

Adicione issues a épicos.

  • issue_ids (obrigatório): Matriz de IDs de issues
  • epic_ids (obrigatório): Matriz de IDs de épicos

Gerenciamento de Épicos (1 ferramenta)

zenhub_create_epic

Crie um novo épico no ZenHub.

  • title (obrigatório): Título do épico
  • repository_id (obrigatório): ID do repositório
  • body (opcional): Descrição do épico

Gerenciamento de Workspaces (4 ferramentas)

zenhub_get_user_workspaces

Obtenha todos os workspaces acessíveis ao usuário atual.

  • query (opcional): Consulta de pesquisa para filtrar workspaces
  • first (opcional): Número de workspaces a retornar (padrão: 20)

zenhub_get_user_organizations

Obtenha todas as organizações ZenHub acessíveis ao usuário atual.

  • query (opcional): Consulta de pesquisa para filtrar organizações
  • first (opcional): Número de organizações a retornar (padrão: 10)

zenhub_get_organization_workspaces

Obtenha todos os workspaces dentro de uma organização ZenHub específica.

  • organization_id (obrigatório): ID da organização ZenHub
  • query (opcional): Consulta de pesquisa para filtrar workspaces
  • first (opcional): Número de workspaces a retornar (padrão: 20)

zenhub_create_workspace

Crie um novo workspace no ZenHub.

  • name (obrigatório): Nome do workspace
  • description (opcional): Descrição do workspace
  • organization_id (obrigatório): ID da organização ZenHub
  • repository_ids (obrigatório): Matriz de IDs de repositórios GitHub
  • default_repository_id (opcional): ID do repositório padrão

Gerenciamento de Sprints (2 ferramentas)

zenhub_create_sprint

Crie um novo sprint.

  • name (obrigatório): Nome do sprint
  • start_date (obrigatório): Data de início (formato ISO)
  • end_date (obrigatório): Data de término (formato ISO)
  • workspace_id (obrigatório): ID do workspace
  • timezone (opcional): Identificador de fuso horário
  • settings (opcional): Objeto de configurações do sprint

zenhub_add_issues_to_sprints

Adicione issues a sprints.

  • issue_ids (obrigatório): Matriz de IDs de issues
  • sprint_ids (obrigatório): Matriz de IDs de sprints

Arquitetura

O servidor usa uma arquitetura modular para fácil expansão:

src/
├── index.ts           # Main MCP server
├── types.ts           # TypeScript interfaces
└── tools/
    ├── index.ts       # Tool registry
    ├── base.ts        # Base tool class
    ├── queries.ts     # Query tools
    ├── issues.ts      # Issue management tools
    ├── epics.ts       # Epic management tools
    ├── workspaces.ts  # Workspace management tools
    └── sprints.ts     # Sprint management tools

Adicionando Novas Ferramentas

  1. Crie uma nova classe de ferramenta estendendo BaseTool no arquivo de categoria apropriado
  2. Adicione-a ao array de exportação de ferramentas
  3. A ferramenta será automaticamente registrada no servidor MCP

Referência de Operações Disponíveis

Todas as 176 operações GraphQL disponíveis do ZenHub estão documentadas em:

  • zenhub_api_operations.json - Lista completa de operações com descrições
  • mutations.json - Todas as 157 mutações
  • queries.json - Todas as 19 consultas

A implementação atual cobre 54 de 176 operações (30,7%)

Desenvolvimento

npm run dev

Variáveis de Ambiente

  • ZENHUB_API_KEY (obrigatório): Sua chave de API do ZenHub de Configurações do ZenHub
  • ZENHUB_MCP_CUSTOM_INSTRUCTIONS (opcional): Forneça instruções adicionais para o servidor MCP. Se definido, este valor será anexado às instruções padrão que o servidor envia ao modelo. Use novas linhas regulares ou sequências de escape \n para formatar prompts de múltiplas linhas.

Endpoint GraphQL

Este servidor se conecta a: https://api.zenhub.com/public/graphql