GitLab MCP

GitLab MCP es un servidor del Protocolo de Contexto de Modelos (Model Context Protocol) independiente del entorno de ejecución, más habilidades de agente compartidas para el trabajo con repositorios de GitLab. Codex, Claude Code, Cline y Pi son distribuciones compatibles del mismo núcleo MCP canónico, no implementaciones separadas de GitLab. ChatGPT puede usar el mismo núcleo a través del despliegue remoto de HTTP Streamable.

El proyecto proporciona:

• un servidor MCP de GitLab autocontenido con herramientas tipadas;

• una habilidad general $gitlab;

• $gl-address-comments para discusiones de merge requests sin resolver;

• $gl-fix-ci para el diagnóstico de pipelines y trabajos;

• $gl-publish para la entrega de ramas, commits, pushes y merge requests en borrador;

• flujos de trabajo nativos de GitLab para runners de CI, lint, gobernanza, etiquetas, releases y programación de pipelines, además de gestión de variables de proyecto y grupo de CI/CD segura frente a secretos;

• distribuciones ligeras de Codex, Claude Code, Cline y Pi que reutilizan el mismo núcleo canónico y las mismas habilidades de agente; y

• transporte HTTP Streamable sin estado y metadatos de recursos protegidos por OAuth para el despliegue en ChatGPT.

Comience aquí

El índice de documentación enlaza el conjunto completo de documentación de usuario, operador, desarrollador, seguridad, compatibilidad y releases.

Related MCP server: GitLab MCP Server

Inicio rápido

Para una instalación local desde el código fuente, use Node.js 22 o superior, luego compile y verifique el núcleo MCP canónico:

npm.cmd ci
npm.cmd test
npm.cmd run build

Elija el adaptador que coincida con el entorno de ejecución. Los cuatro adaptadores compatibles consumen el mismo paquete MCP compilado y las mismas habilidades de agente canónicas.

Para Codex, agregue este repositorio a un marketplace local de confianza, instale el plugin gitlab y reinicie o actualice Codex. El manifiesto raíz de Codex, .mcp.json, la precarga y el nombre del artefacto siguen siendo superficies de compatibilidad admitidas. Configure la URL de la instancia y el token en el entorno que lanza Codex:

$env:GITLAB_URL = "https://gitlab.example.com"
$env:GITLAB_TOKEN = "<token>"

Inicie una nueva conversación y pida a Codex que confirme la conexión, por ejemplo:

Use GitLab to tell me which account and instance are connected.

Los usuarios de Claude Code pueden cargar la distribución de plugin nativa materializada, que incluye el mismo servidor MCP y las mismas habilidades de agente canónicas. Consulte la guía del adaptador de Claude Code para la validación de paquetes, la carga con --plugin-dir y la disposición compatible con marketplaces.

Los usuarios de Cline pueden usar el mismo paquete MCP canónico a través de stdio e instalar las habilidades de agente canónicas sin una implementación separada de GitLab. Consulte la guía del adaptador de Cline para la configuración del IDE y de la CLI.

Los usuarios de Pi pueden instalar el paquete dedicado de Pi, que registra el inventario canónico de herramientas MCP a través de un puente stdio ligero y expone las mismas habilidades de agente. Consulte la guía del adaptador de Pi para la instalación del paquete, el manejo de dependencias en tiempo de ejecución y las limitaciones del puente.

Consulte la guía de usuario para obtener orientación sobre tokens con el menor privilegio posible, flujos de trabajo comunes de GitLab y despliegue HTTP en ChatGPT.

Requisitos

• Node.js 22 o superior

• una instancia de GitLab.com, GitLab Dedicated o GitLab autogestionado

• para uso local con stdio, un token de GitLab con los alcances mínimos requeridos por las operaciones que desea realizar

Compilar y verificar

npm.cmd install
npm.cmd test
npm.cmd run adapters:check
npm.cmd run check:bundle
npm.cmd run build
npm.cmd run validate:codex
npm.cmd run validate:claude
npm.cmd run validate:cline
npm.cmd run validate:pi
npm.cmd run check:versions
npm.cmd run check:gitlab-oauth -- https://gitlab.example.com

La ruta del paquete MCP canónico está definida por distribution.json; la configuración actual compila server/dist/gitlab-mcp.cjs. El paquete MCP en sí se genera y se excluye del control de versiones, y luego se incluye en los artefactos de release. Los paquetes de los entornos de ejecución pueden declarar una dependencia de tiempo de ejecución propia; el paquete de Pi, por ejemplo, usa el SDK de MCP para conectar Pi con ese servidor incluido.

distribution.json es la fuente autoritativa de los metadatos de distribución compartidos, incluido el identificador de distribución neutro gitlab, la versión base, la descripción, la licencia, el paquete MCP canónico y la ruta de Skills. Después de modificarlo, ejecute npm run adapters:generate y revise los metadatos generados para Codex/Claude Code/Cline/Pi. npm run adapters:check rechaza la deriva de metadatos y una ruta de Skills canónica faltante, que no sea un directorio o que escape del repositorio.

npm run check:bundle realiza una compilación limpia en memoria y falla si el paquete canónico contiene referencias de implementación específicas del entorno de ejecución. npm run check:versions verifica que los metadatos de release generados del paquete y de Codex sigan alineados con distribution.json. El manifiesto del plugin de Codex puede añadir metadatos de compilación de Codex después de + sin cambiar la versión base de distribución. SERVER_VERSION es propiedad independiente del núcleo MCP neutro y solo se incrementa cuando cambia el propio núcleo en tiempo de ejecución.

El límite entre el núcleo neutro y los adaptadores está documentado en ADR-001. Las decisiones de la auditoría centrada GEN-08 y de identidad están registradas en docs/GENERALISATION_AUDIT.md.

Integración continua

Los pipelines de merge requests, rama predeterminada y etiquetas de GitLab ejecutan comprobaciones de sintaxis, pruebas, cobertura, dependency-cruiser, formato/lint, una auditoría de dependencias de producción, una compilación limpia del paquete y pruebas de humo de stdio/HTTP incluidas. Las plantillas de SAST y detección de secretos de GitLab también están habilitadas. Codex, Claude Code, Cline y Pi tienen cada uno una validación de adaptador centrada después de la compilación canónica; esos trabajos validan el empaquetado del entorno de ejecución y el arranque de MCP sin repetir la matriz de seguridad de Node.

Los pipelines de etiquetas además publican el archivo determinista de Codex con su SBOM de CycloneDX y SHA256SUMS, más archivos reproducibles de Claude Code, Cline y Pi con MCP + Skills y sus sidecars .sha256 correspondientes, como artefactos de trabajo de GitLab. La compuerta final del conjunto de releases requiere exactamente los cuatro entornos de ejecución compatibles y compara sus resúmenes (digests) del paquete MCP canónico y de Skills. Los releases no se consideran completos hasta que los artefactos se verifican según docs/PUBLICATION_CHECKLIST.md.

El inventario confirmado docs/gitlab-tool-contracts.json invoca cada herramienta registrada con entradas válidas en los límites y fija su clasificación de seguridad, método HTTP, ruta codificada, mapeo de consulta/cuerpo y modo de respuesta acotado. La cobertura cubre todos los módulos de producción y falla por debajo del 90 % de líneas, 80 % de funciones o 75 % de ramas; añadir una herramienta sin una entrada en el inventario hace fallar la prueba.

Los trabajos de sintaxis y pruebas se ejecutan tanto en node:22-alpine como en node:24-alpine; el trabajo de cobertura con umbral se ejecuta en Node 22. Los trabajos principales requieren un runner de Linux sin etiquetar que pueda ejecutar estas imágenes y alcanzar el registro npm. Las plantillas de seguridad extraen sus imágenes de analizadores del registro de GitLab. No se requiere modo privilegiado para los trabajos principales de Node.js. Configure al menos un runner de proyecto, grupo o instancia que acepte trabajos sin etiquetar y permita que los trabajos se ejecuten durante al menos 10 minutos antes de exigir pipelines exitosos para el merge.

Autenticación local de Codex

Establezca la URL de la instancia y el token en el entorno que lanza Codex:

$env:GITLAB_URL = "https://gitlab.example.com"
$env:GITLAB_TOKEN = "<token>"

GITLAB_URL debe usar HTTPS de forma predeterminada y rechaza credenciales incrustadas, consultas y fragmentos. Para una instancia de desarrollo de GitLab explícitamente local/privada que no pueda usar TLS, establezca GITLAB_ALLOW_INSECURE_HTTP=true. La anulación se rechaza en producción y para nombres de host públicos; acepta loopback, IPs de red privada, hosts de una sola etiqueta y los sufijos de desarrollo privado .localhost, .local, .internal y .home.arpa.

GITLAB_URL tiene como valor predeterminado https://gitlab.com. El .mcp.json de Codex inicia el servidor incluido a través de stdio y carga el adaptador de distribución ligero de Codex antes del núcleo neutro. Los tokens se leen en tiempo de ejecución y nunca se almacenan en una distribución.

Use los alcances de token más restringidos que cubran la tarea. El trabajo de solo lectura puede usar un token orientado a lectura; las mutaciones de repositorio, issues, merge requests o CI requieren los permisos correspondientes de la API de GitLab.

Descubrimiento de capacidades

Llame a get_gitlab_capabilities antes de diagnosticar si una operación de GitLab no es compatible, no tiene licencia, está deshabilitada o simplemente es inaccesible para la credencial actual. Usa solo solicitudes de solo lectura a /user, /version, /metadata, /personal_access_tokens/self y (cuando la credencial no es un token de acceso personal) /oauth/token/info. Los diagnósticos de OAuth informan alcances y vida útil restante, pero nunca exponen el token ni el identificador de la aplicación OAuth. GitLab puede ocultar u omitir estos endpoints, especialmente en versiones autogestionadas antiguas o para no administradores, por lo que los resultados ambiguos se informan como unknown en lugar de adivinarse.

Cada capacidad es uno de available, unavailable, permission_required, license_required, not_configured o unknown, con una razón concisa y evidencia de respaldo cuando sea útil. Pase detailed: true para obtener resultados normalizados por sonda, o refresh: true para omitir la caché.

Los resultados se almacenan en caché durante 60 segundos por URL de instancia normalizada e identidad de credencial autenticada. La clave de caché contiene un resumen SHA-256 unidireccional, nunca el token bearer sin procesar. Las entradas expiran después de 60 segundos, se omiten con refresh y separan naturalmente instancias o credenciales cambiadas. Las entradas expiradas se eliminan de forma oportunista, y un límite LRU de 256 entradas proporciona un límite de memoria estricto. La caché es solo en memoria y se limpia cuando se reinicia el proceso del servidor MCP.

Servidor HTTP

Para desarrollo local:

$env:MCP_PUBLIC_URL = "https://mcp.example.com/mcp"
$env:GITLAB_URL = "https://gitlab.example.com"
npm.cmd run start:http

El modo HTTP requiere un token bearer en cada solicitud /mcp. Un token del lado del servidor está deshabilitado de forma predeterminada. ALLOW_SERVER_TOKEN_HTTP=true existe solo para pruebas privadas controladas y no debe usarse para un despliegue compartido.

Establezca MCP_READ_ONLY=true para un despliegue solo de inspección. En ese modo, el servidor registra solo las herramientas anotadas como de solo lectura y anuncia el alcance OAuth read_api de GitLab. El modo predeterminado con escritura habilitada expone el conjunto completo de herramientas y requiere api. El servidor valida cada anotación de herramienta durante el registro, de modo que una herramienta sin clasificar o mutadora no pueda entrar silenciosamente en la superficie de solo lectura.

Al vincularse al comodín IPv4 0.0.0.0 o al comodín IPv6 ::, establezca MCP_ALLOWED_HOSTS a una lista blanca separada por comas de nombres de host públicos. Coloque el servicio detrás de HTTPS y establezca MCP_PUBLIC_URL a su URL /mcp pública canónica. El modo de producción requiere MCP_PUBLIC_URL, rechaza credenciales incrustadas, consultas, fragmentos y rutas que no sean /mcp, y requiere HTTPS. MCP_ALLOW_INSECURE_PUBLIC_URL=true está disponible solo para desarrollo local explícito en un oyente de bucle local y se rechaza en producción o en un host público. ALLOW_SERVER_TOKEN_HTTP=true se limita igualmente a pruebas privadas de bucle local y no debe usarse para una implementación compartida.

Utilice la herramienta de solo lectura get_runtime_info después de la instalación o implementación para confirmar las versiones del núcleo/distribución, el modo de implementación, el filtrado de solo lectura y la huella SHA-256 determinista del inventario de herramientas registradas.

Los cuerpos de las solicitudes HTTP MCP están limitados a 8 MiB de forma predeterminada. Esto permite confirmaciones de múltiples archivos acotadas y otras cargas útiles de herramientas grandes legítimas, al tiempo que evita el almacenamiento en búfer de solicitudes ilimitado. Establezca MCP_MAX_REQUEST_BYTES a un entero de 65 536 a 26 214 400 bytes para usar un límite de implementación diferente. Cualquier proxy inverso frente al servidor debe permitir al menos el mismo tamaño de solicitud.

Las implementaciones HTTP de larga duración también acotan el estado de autenticación y de solicitudes:

• MCP_TOKEN_CACHE_MAX_ENTRIES limita las identidades de portador validadas, por defecto 256, con un TTL de 60 segundos y desalojo LRU;

• MCP_AUTH_FAILURE_LIMIT limita los tokens rechazados por dirección conectada directamente dentro de MCP_AUTH_FAILURE_WINDOW_MS, por defecto 20 fallos por 60 segundos;

• MCP_AUTH_FAILURE_MAX_ENTRIES acota el estado de seguimiento de fallos, por defecto 1024;

• MCP_MAX_CONCURRENT_REQUESTS limita las solicitudes MCP activas, por defecto 32; y

• MCP_MAX_CONCURRENT_REQUESTS_PER_IDENTITY limita las solicitudes de un usuario de GitLab validado, por defecto 4.

Configure límites complementarios de tasa y conexión en el proxy inverso TLS. La aplicación utiliza deliberadamente la dirección del par directo en lugar de confiar en las cabeceras reenviadas de forma predeterminada, por lo que los límites de IP de cliente a nivel de proxy deben aplicarse antes de que el tráfico llegue a este servicio.

El endpoint /health no autenticado es una comprobación de actividad del proceso sin topología. /ready es una comprobación de preparación separada y devuelve 503 cuando su sonda de dependencia no está disponible. Cada respuesta incluye un X-Request-Id generado; los fallos MCP internos registran solo ese identificador y el tipo de error. Los integradores pueden proporcionar un observador de finalización de solicitudes para métricas sin recibir tokens de portador ni cargas útiles de solicitud.

Después de implementar, verifique los metadatos de recursos públicos y ambas semánticas de salud:

npm.cmd run check:mcp-deployment -- https://mcp.example.com/mcp

Modelo de seguridad

• Las herramientas anuncian anotaciones de solo lectura, escritura y destructivas.

• create_commit solo admite acciones de archivo no destructivas; el borrado y las actualizaciones de confirmación forzada requieren la herramienta create_destructive_commit anotada por separado con campos de seguridad de concurrencia.

• Los cuerpos de respuesta de GitLab, incluidos los registros de trabajos, los artefactos y los errores de API, se transmiten bajo límites estrictos de bytes y siguen cubiertos por los tiempos de espera de solicitud;

• Los errores de API se normalizan sin repetir credenciales;

• el descubrimiento de capacidades censura la evidencia de errores y nunca lee variables de CI privadas ni endpoints de mutación;

• los tokens de portador HTTP se validan contra la instancia de GitLab configurada y se almacenan en caché mediante un hash de token unidireccional en una caché TTL/LRU acotada;

• las credenciales rechazadas y las solicitudes concurrentes están acotadas sin registrar tokens ni detalles de identidad privados;

• el modo HTTP desafía las solicitudes no autenticadas con metadatos de recursos protegidos;

• las herramientas HTTP anuncian esquemas de seguridad OAuth por herramienta o de token de servidor privado, además de desafíos de reautorización visibles por el modelo; y

• las habilidades requieren intención explícita para fusiones, aprobaciones, borrados, resolución de discusiones y cambios de estado de CI.

Licencia

MIT