Servidor MCP de GitLab avanzado

Servidor MCP de GitLab avanzado: 44 herramientas en 18 tipos de entidades con arquitectura CQRS, OAuth 2.1 y múltiples modos de transporte.

Inicio rápido

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@structured-world/gitlab-mcp"],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "https://gitlab.com"
      }
    }
  }
}

Requisitos: Node.js >= 24

Related MCP server: GitLab MCP Server

Aspectos destacados

• 44 herramientas en 18 tipos de entidades: proyectos, solicitudes de fusión (merge requests), pipelines, elementos de trabajo, wiki y más

• Arquitectura CQRS — browse_* para consultas, manage_* para comandos

• Resiliencia de conexión — Inicio limitado, reconexión automática con retroceso exponencial, modo desconectado cuando GitLab no está accesible

• Soporte multi-instancia — Conéctese a múltiples instancias de GitLab con OAuth y limitación de tasa por instancia

• Múltiples transportes — stdio, SSE, StreamableHTTP

• OAuth 2.1 — Autenticación por usuario a través de Claude Custom Connector

• Modo de solo lectura — Operación segura para entornos de producción

• Auto-descubrimiento — Detecta la configuración de GitLab desde remotos de git

• Control detallado — Habilitar/deshabilitar grupos de herramientas, filtrar acciones, personalizar descripciones

• Soporte Docker — ghcr.io/structured-world/gitlab-mcp:latest

Documentación

La documentación completa está disponible en gitlab-mcp.sw.foundation

Referencia de herramientas autogenerada

Para la referencia completa de herramientas con parámetros:

# View locally
yarn list-tools --detail

# Generate documentation
yarn list-tools --export --toc > docs/tools/api-reference.md

Consulte la Referencia completa de la API para la documentación de herramientas autogenerada.

Docker

# HTTP mode
docker run -e PORT=3002 -e GITLAB_TOKEN=your_token -p 3333:3002 \
  ghcr.io/structured-world/gitlab-mcp:latest

# stdio mode
docker run -i --rm -e GITLAB_TOKEN=your_token \
  ghcr.io/structured-world/gitlab-mcp:latest

Resiliencia de conexión

El servidor maneja los problemas de conectividad de GitLab con elegancia:

• Inicio limitado — El servidor se inicia dentro de GITLAB_INIT_TIMEOUT_MS (por defecto 5s) independientemente de la disponibilidad de GitLab

• Modo desconectado — Cuando GitLab no está accesible (estado disconnected/failed), solo se expone la herramienta manage_context, con acciones locales como whoami, switch_profile y set_scope para diagnósticos. Durante la reconexión activa (estado connecting), la lista completa de herramientas permanece disponible para que los clientes MCP no pierdan su catálogo de herramientas durante breves interrupciones. Los clientes MCP son notificados de los cambios en la disponibilidad de herramientas a través de tools/list_changed

• Reconexión automática — Reconexión con retroceso exponencial (5s → 60s) con un jitter de ±10%

• Clasificación de errores — Los errores transitorios (red, 5xx, tiempos de espera) activan la reconexión automática. Los errores de autenticación/configuración al inicio pasan al estado failed (sin reconexión automática). La revocación del token a mitad de la sesión se detecta mediante una comprobación autenticada HEAD /api/v4/user que se ejecuta junto con cada comprobación de estado periódica (solo modo de token estático; omitido en modo OAuth). Un 401 o 403 en esta comprobación hace que la instancia pase al estado failed inmediatamente.

• Monitor de salud de la instancia — Cada URL de instancia monitoreada tiene su propia máquina de estados XState. Las URLs de OAuth no rastreadas actualmente pasan como accesibles.

Flags de características

Contribución

Consulte CONTRIBUTING.md para la configuración de desarrollo, pruebas y directrices de PR.

Apoye el proyecto

USDT (TRC-20): TFDsezHa1cBkoeZT5q2T49Wp66K8t2DmdA

Licencia

Licencia Apache 2.0 — consulte LICENSE para más detalles.

Basado en zereight/gitlab-mcp (MIT). Consulte LICENSE.MIT.