ZenHub

Accede a la API GraphQL de ZenHub para gestionar flujos de trabajo de proyectos y mejorar la productividad.

GitHub
1
Prueba este MCPPatrocinado

Documentación

Servidor MCP de ZenHub

Un servidor MCP (Protocolo de Contexto de Modelo) que proporciona acceso completo a la API GraphQL de ZenHub.

Características

  • Acceso GraphQL completo: Ejecuta cualquier consulta GraphQL contra la API de ZenHub
  • Operaciones comunes: Herramientas integradas para tareas frecuentes como crear issues, épicas, espacios de trabajo y sprints
  • Autenticación segura: Autenticación basada en clave API para todas las solicitudes
  • Manejo de errores: Manejo integral de errores y validación

Instalación

Para desarrollo

npm install
npm run build

Configurar la clave API

  1. Obtén tu clave API de ZenHub en Configuración de ZenHub

  2. Establece la variable de entorno:

export ZENHUB_API_KEY=your_api_key_here

O crea un archivo .env (copia desde .env.example):

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

Para Claude Desktop

  1. Compila el servidor:
npm install
npm run build
  1. Agrega a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):
{
  "mcpServers": {
    "zenhub": {
      "command": "npx",
      "args": ["zenhub-mcp-server"],
      "env": {
        "ZENHUB_API_KEY": "your_api_key_here"
      }
    }
  }
}

Para Cursor

  1. Compila el servidor:
npm install
npm run build
  1. En Cursor, ve a Configuración > Servidores MCP y agrega:
{
  "name": "zenhub",
  "command": "node",
  "args": ["/path/to/zenhub-mcp/dist/index.js"],
  "env": {
    "ZENHUB_API_KEY": "zh_",
    "GITHUB_PAT": "github_pat_"
  }
}

O usa el servidor de desarrollo:

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

Herramientas

El servidor proporciona 54 herramientas en 10 categorías, implementando las operaciones de ZenHub más utilizadas:

No se requiere clave API en las llamadas a herramientas - Establece la variable de entorno ZENHUB_API_KEY una vez y usa todas las herramientas.

Herramientas de consulta (7 herramientas)

zenhub_query

Ejecuta cualquier consulta GraphQL contra la API de ZenHub.

  • query (obligatorio): Cadena de consulta GraphQL
  • variables (opcional): Variables para la consulta

zenhub_search_issues

Busca issues en un pipeline.

  • pipeline_id (obligatorio): ID del pipeline donde buscar
  • query (opcional): Consulta de búsqueda para el título
  • filters (opcional): Objeto con filtros para etiquetas y asignados

zenhub_search_issues_in_repository

Busca y filtra issues dentro de un repositorio.

  • repository_id (obligatorio): ID del repositorio donde buscar
  • query (opcional): Consulta de búsqueda
  • filters (opcional): Opciones de filtro

zenhub_get_workspace_issues

Obtiene todos los issues en un espacio de trabajo (paginado).

  • workspace_id (obligatorio): ID del espacio de trabajo
  • after (opcional): Cursor para paginación

zenhub_get_viewer

Obtiene información del usuario actual de ZenHub.

zenhub_get_issue_by_info

Busca un issue por repositorio y número de issue.

  • repository_gh_id (obligatorio): ID del repositorio de GitHub
  • issue_number (obligatorio): Número del issue

zenhub_get_repositories

Busca repositorios por sus IDs de GitHub.

  • repository_gh_ids (obligatorio): Matriz de IDs de repositorios de GitHub

Gestión de issues (13 herramientas)

zenhub_create_issue

Crea un nuevo issue de GitHub a través de ZenHub.

  • title (obligatorio): Título del issue
  • repository_id (obligatorio): ID del repositorio
  • body (opcional): Descripción del issue
  • labels (opcional): Matriz de nombres de etiquetas
  • assignees (opcional): Matriz de nombres de usuario de GitHub

zenhub_close_issues

Cierra uno o más issues.

  • issue_ids (obligatorio): Matriz de IDs de issues

zenhub_reopen_issues

Reabre uno o más issues cerrados.

  • issue_ids (obligatorio): Matriz de IDs de issues
  • pipeline_id (obligatorio): ID del pipeline al que mover los issues
  • position (opcional): Posición en el pipeline (INICIO o FIN)

zenhub_move_issue

Mueve issues a una posición en un pipeline.

  • issue_ids (obligatorio): Matriz de IDs de issues
  • pipeline_id (obligatorio): ID del pipeline al que mover los issues
  • position (opcional): Posición en el pipeline (basada en 0)

zenhub_add_assignees_to_issues

Agrega asignados a múltiples issues.

  • issue_ids (obligatorio): Matriz de IDs de issues
  • assignees (obligatorio): Matriz de nombres de usuario de GitHub

zenhub_add_labels_to_issues

Agrega etiquetas a múltiples issues.

  • issue_ids (obligatorio): Matriz de IDs de issues
  • labels (obligatorio): Matriz de nombres de etiquetas

zenhub_set_estimate

Establece una estimación para un issue.

  • issue_id (obligatorio): ID del issue
  • value (obligatorio): Valor de la estimación

zenhub_set_multiple_estimates

Establece estimaciones en múltiples issues.

  • estimates (obligatorio): Matriz de pares de ID de issue y valor de estimación

zenhub_add_issues_to_epics

Agrega issues a épicas.

  • issue_ids (obligatorio): Matriz de IDs de issues
  • epic_ids (obligatorio): Matriz de IDs de épicas

Gestión de épicas (1 herramienta)

zenhub_create_epic

Crea una nueva épica en ZenHub.

  • title (obligatorio): Título de la épica
  • repository_id (obligatorio): ID del repositorio
  • body (opcional): Descripción de la épica

Gestión de espacios de trabajo (4 herramientas)

zenhub_get_user_workspaces

Obtiene todos los espacios de trabajo accesibles para el usuario actual.

  • query (opcional): Consulta de búsqueda para filtrar espacios de trabajo
  • first (opcional): Número de espacios de trabajo a devolver (predeterminado: 20)

zenhub_get_user_organizations

Obtiene todas las organizaciones de ZenHub accesibles para el usuario actual.

  • query (opcional): Consulta de búsqueda para filtrar organizaciones
  • first (opcional): Número de organizaciones a devolver (predeterminado: 10)

zenhub_get_organization_workspaces

Obtiene todos los espacios de trabajo dentro de una organización específica de ZenHub.

  • organization_id (obligatorio): ID de la organización de ZenHub
  • query (opcional): Consulta de búsqueda para filtrar espacios de trabajo
  • first (opcional): Número de espacios de trabajo a devolver (predeterminado: 20)

zenhub_create_workspace

Crea un nuevo espacio de trabajo en ZenHub.

  • name (obligatorio): Nombre del espacio de trabajo
  • description (opcional): Descripción del espacio de trabajo
  • organization_id (obligatorio): ID de la organización de ZenHub
  • repository_ids (obligatorio): Matriz de IDs de repositorios de GitHub
  • default_repository_id (opcional): ID del repositorio predeterminado

Gestión de sprints (2 herramientas)

zenhub_create_sprint

Crea un nuevo sprint.

  • name (obligatorio): Nombre del sprint
  • start_date (obligatorio): Fecha de inicio (formato ISO)
  • end_date (obligatorio): Fecha de fin (formato ISO)
  • workspace_id (obligatorio): ID del espacio de trabajo
  • timezone (opcional): Identificador de zona horaria
  • settings (opcional): Objeto de configuración del sprint

zenhub_add_issues_to_sprints

Agrega issues a sprints.

  • issue_ids (obligatorio): Matriz de IDs de issues
  • sprint_ids (obligatorio): Matriz de IDs de sprints

Arquitectura

El servidor utiliza una arquitectura modular para facilitar la expansión:

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

Agregar nuevas herramientas

  1. Crea una nueva clase de herramienta que extienda BaseTool en el archivo de categoría correspondiente
  2. Agrégala al arreglo de exportación de herramientas
  3. La herramienta se registrará automáticamente con el servidor MCP

Referencia de operaciones disponibles

Las 176 operaciones GraphQL disponibles de ZenHub están documentadas en:

  • zenhub_api_operations.json - Lista completa de operaciones con descripciones
  • mutations.json - Las 157 mutaciones
  • queries.json - Las 19 consultas

La implementación actual cubre 54 de 176 operaciones (30.7%)

Desarrollo

npm run dev

Variables de entorno

  • ZENHUB_API_KEY (obligatorio): Tu clave API de ZenHub desde Configuración de ZenHub
  • ZENHUB_MCP_CUSTOM_INSTRUCTIONS (opcional): Proporciona instrucciones adicionales para el servidor MCP. Si se establece, este valor se agregará a las instrucciones predeterminadas que el servidor envía al modelo. Usa saltos de línea regulares o secuencias de escape \n para formatear indicaciones de varias líneas.

Endpoint GraphQL

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