Gitlab MCP Server

Servidor MCP de GitLab

Conecta tu asistente de IA a GitLab para que pueda revisar merge requests, diagnosticar pipelines, gestionar issues y redactar releases — en lenguaje natural. Un único binario estático (o un contenedor), más de 1000 herramientas de GitLab sobre la API completa REST + GraphQL, compatible con Claude, Cursor, VS Code y cualquier cliente MCP.

Tú hablas con tu asistente de IA; él hace el trabajo en GitLab. Sin IDs de proyecto, endpoints de API ni JSON que recordar.

10 359 tokens de contexto de inicio por defecto, igual en todos los niveles de GitLab (1 694 con GITLAB_MCP_CAPABILITY_SURFACE=minimal). Dos herramientas alcanzan todo el catálogo; medido con el tokenizador cl100k_base y verificado en CI en cada commit. Cómo se mide

"Revisa el merge request !15 — ¿es seguro fusionarlo?" · "¿Por qué falló el último pipeline?" · "Lista los issues abiertos asignados a mí" · "Genera notas de release de v1.0 a v2.0"

🤖 ¿Usas un asistente de IA? Dale la URL de este repositorio y pídele que instale el servidor para tu cliente. Todo lo que un modelo necesita para hacerlo sin intervención — la configuración declarativa por cliente, los one-liners de claude mcp add y los valores predeterminados — está en llms.txt (sin asistente interactivo requerido).

Instalación en 60 segundos

Elige una opción. Cada camino termina con que escribes un prompt a tu asistente. Cada canal tiene una guía completa: Instalación.

¿Quieres mirar antes de instalar? El inspector de navegador inicia sesión con OAuth y llama al endpoint alojado en modo solo lectura desde una pestaña del navegador — sin descargar nada. Ejecutarlo tú mismo sigue siendo la forma de seguir usándolo.

Instalación con un clic

Cliente	Botón de un clic	Paso del token
VS Code		te solicita (enmascarado)
VS Code Insiders		te solicita (enmascarado)
Cursor		edita YOUR_GITLAB_TOKEN
LM Studio		edita YOUR_GITLAB_TOKEN
Kiro		edita YOUR_GITLAB_TOKEN
Claude Desktop		interfaz de ajustes

Cada botón registra el servidor basado en Docker (descarga automáticamente la imagen en la primera ejecución; necesitas Docker instalado). La fila de Claude Desktop en su lugar descarga una extensión de escritorio .mcpb nativa (macOS universal, Windows y Linux amd64 y arm64; sin Docker). Ábrela con Claude Desktop, o en Linux usa Extensiones > Instalar extensión..., y completa los ajustes. ¿Necesitas un token? Crea un Personal Access Token con el alcance api. ¿GitLab auto-gestionado? Añade una variable de entorno GITLAB_URL en la configuración MCP de tu cliente después de la instalación.

Claude Code (claude mcp add)

Docker (sin instalación — descarga la imagen en la primera ejecución):

claude mcp add gitlab --env GITLAB_TOKEN=glpat-xxxx --transport stdio \
  -- docker run -i --rm -e GITLAB_TOKEN ghcr.io/jmrplens/gitlab-mcp-server:latest

O instala primero el binario nativo y luego regístralo:

# Any platform (npm/pnpm) — downloads only your platform's prebuilt binary
npx -y @jmrp.io/gitlab-mcp-server          # zero install; clients launch it directly
npm install -g @jmrp.io/gitlab-mcp-server  # or install globally (npm)
pnpm add -g @jmrp.io/gitlab-mcp-server     # or globally (pnpm)
# Any platform (Python: uv/pipx/pip) — platform wheel carrying the same native binary
uvx jmrplens-gitlab-mcp-server             # zero install; clients launch it directly
pipx install jmrplens-gitlab-mcp-server    # or install globally (pipx)
pip install jmrplens-gitlab-mcp-server     # or into the active environment (pip)
# Linux wheels need glibc; on musl systems such as Alpine use the Docker image instead
# Any platform (.NET 10 SDK) — a .NET tool whose entry point is the same native binary
dnx gitlab-mcp-server                      # zero install; clients launch it directly
dotnet tool install -g gitlab-mcp-server   # or install globally (dotnet tool)
# macOS/Linux (Homebrew)
brew install jmrplens/tap/gitlab-mcp-server
# Linux/macOS (script)
curl -fsSL https://raw.githubusercontent.com/jmrplens/gitlab-mcp-server/main/scripts/install.sh | sh
# Windows (winget)
winget install --id jmrplens.gitlab-mcp-server -e
# Windows (PowerShell)
irm https://raw.githubusercontent.com/jmrplens/gitlab-mcp-server/main/scripts/install.ps1 | iex

claude mcp add gitlab --env GITLAB_TOKEN=glpat-xxxx -- gitlab-mcp-server

Los clientes que lanzan servidores con npx, uvx o dnx no necesitan instalación en absoluto — apúntalos a npx -y @jmrp.io/gitlab-mcp-server, uvx jmrplens-gitlab-mcp-server o dnx gitlab-mcp-server.

¿GitLab auto-gestionado? Añade --env GITLAB_URL=https://gitlab.example.com (y, para un certificado autofirmado, monta la CA y establece --env SSL_CERT_FILE=/path/to/ca-bundle.crt; GITLAB_MCP_SKIP_TLS_VERIFY=true es la alternativa contundente, y el modo OAuth la rechaza para una instancia que no sea de loopback).

Ejecútalo una vez para verificar la instalación

Iniciado en una terminal, o con doble clic en Windows, sin GITLAB_TOKEN configurado, el binario imprime qué es y qué necesita y espera Enter, para que puedas confirmar la instalación antes de configurar nada. La configuración en sí vive en el JSON de tu cliente MCP, abajo.

JSON manual (Claude Desktop, Cursor, VS Code, …)

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "env": { "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "/path/to/gitlab-mcp-server",
      "env": { "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

"command": "docker",
"args": ["run", "-i", "--rm", "-e", "GITLAB_TOKEN", "ghcr.io/jmrplens/gitlab-mcp-server:latest"]

Pruébalo sin instalar nada (endpoint alojado)

Una instancia pública se ejecuta en https://mcp.jmrp.io/gitlab — nada que instalar, sin cuenta más allá de tu propio token de GitLab. Apunta cualquier cliente MCP compatible con HTTP hacia ella:

{
  "mcpServers": {
    "gitlab": {
      "type": "http",
      "url": "https://mcp.jmrp.io/gitlab",
      "headers": { "Authorization": "Bearer glpat-xxxxxxxxxxxx" }
    }
  }
}

El endpoint se ejecuta en modo OAuth, por lo que la credencial viaja como Authorization: Bearer — un personal access token de GitLab funciona allí, verificado exactamente como uno de OAuth, que es lo que mantiene funcionando a los clientes sin flujo OAuth (y el uso sin interfaz). Viaja por solicitud y nunca se almacena en el servidor. Un cliente que habla el flujo OAuth no necesita ningún encabezado: el 401 lleva un desafío RFC 9728 que sigue para autorizar en el navegador. PRIVATE-TOKEN es el encabezado de modo heredado y no se acepta aquí; la instancia está fijada a https://gitlab.com, por lo que GITLAB-URL se ignora.

Un token read_api se acepta y recibe una superficie de herramientas de solo lectura — la verificación de escritura es por acción, por lo que una credencial que no puede romper nada es una forma compatible de usar el endpoint en lugar de una rechazada.

Dos páginas lo hacen aún más fácil. La tarjeta del servidor lista todo el catálogo sin ninguna credencial y lleva configuración de copiar y pegar para Claude Code, Cursor y VS Code — incluido el ID de cliente OAuth que esos clientes necesitan. El inspector de navegador llama al mismo endpoint en modo solo lectura desde una pestaña del navegador: inicia sesión con OAuth, elige una herramienta, lee el JSON-RPC crudo que devuelve — nada instalado.

Es la forma más rápida de probar el servidor, y la forma correcta de seguir usándolo sigue siendo localmente (cualquier opción anterior) — por una razón concreta, no como descargo de responsabilidad: tu token y cada solicitud pasan por la máquina de otra persona. Ejecutarlo localmente significa que tus credenciales y tu tráfico de GitLab nunca salen de tu computadora, lo que también lo convierte en la única opción sensata para una instancia privada auto-gestionada.

El endpoint es HTTP de flujo sin estado en la superficie dynamic predeterminada: POST es el transporte y un GET autenticado responde 405 por diseño; sin credencial, cualquier método responde 401 llevando el desafío RFC 6750 que un cliente OAuth sigue — un curl desnudo que recibe 401 es el endpoint funcionando, no fallando. https://mcp.jmrp.io/gitlab/health no necesita credencial y responde 200 con {"status":"ok",…}. Un despliegue HTTP auto-alojado también puede ejecutar --auth-mode=oauth --gitlab-url=https://gitlab.com --public-url=https://mcp.example.com/mcp (ambos son requeridos: OAuth necesita una instancia fija, y --public-url es el identificador de recurso RFC 9728 — pasa exactamente la URL con la que tus clientes están configurados, ya que un cliente descarta metadatos que nombren una diferente), donde los clientes descubren GitLab como el servidor de autorización a través de esos metadatos y autorizan en el navegador en lugar de copiar tokens — consulta Configuración de la aplicación OAuth. Es uno de los servidores listados en mcp.jmrp.io, un directorio de los servidores MCP que mantengo, cada uno accesible en su propio endpoint; https://mcp.jmrp.io/servers.json es la misma lista para clientes automatizados.

Es un servicio personal, ejecutado por una persona y ofrecido tal cual: sin SLA, sin canal de soporte y sin promesa de que no cambie la próxima semana. No añade cuota propia — cada llamada gasta los límites propios de GitLab.com, bajo tu propio token. Y se mueve por sí solo, normalmente a la versión más reciente, por lo que lo que sirve nunca es una versión fijada.

Entonces solo pregunta: abre tu cliente de IA y prueba "Lista mis proyectos de GitLab." Consulta la guía de inicio para detalles por cliente y más ejemplos de prompts.

Por qué este servidor

• GitLab en lenguaje natural. La IA traduce "¿es seguro fusionar el MR !15?" en las llamadas API correctas. No tocas endpoints, IDs ni JSON.
• Toda la plataforma — más de 1000 herramientas. Amplia cobertura de GitLab REST v4 + GraphQL: proyectos, ramas, tags, releases, merge requests, issues, pipelines, jobs, grupos, usuarios, wikis, entornos, despliegues, paquetes, registro de contenedores, runners, feature flags, variables CI/CD, seguridad, administración, tokens y más.
• Bajo consumo de tokens por defecto. La superficie dinámica predeterminada expone solo 2 herramientas (find + execute) mientras alcanza todo el catálogo — así cabe en la ventana de contexto de cualquier cliente. (Huella de tokens →)
• Seguro por diseño. Modo solo lectura, modo seguro (vista previa en seco de cada mutación), opciones TLS para GitLab auto-gestionado y compuertas continuas de calidad/seguridad de SonarCloud.
• Se ejecuta en cualquier lugar. Un binario estático o contenedor; Windows, Linux y macOS; amd64 y arm64; stdio (escritorio) y HTTP (remoto).

Superficies de herramientas

El servidor puede presentar GitLab en tres formas, controladas por GITLAB_MCP_TOOL_SURFACE. La predeterminada no requiere configuración.

Los conteos de herramientas escalan con tu edición de GitLab (GITLAB_MCP_TIER); los niveles superiores exponen más acciones. Consulta Dynamic Toolset y Meta-Tools Reference para el modelo de clasificación, salvaguardas de seguridad y catálogos completos. Para ejecuciones dinámicas donde los recursos dominan el contexto, establece GITLAB_MCP_CAPABILITY_SURFACE=minimal.

Huella de tokens

Medido con go run ./cmd/audit_tokens/ -footprint contra el catálogo actual. Los totales estiman el contexto de inicio visible para un cliente MCP: esquemas de herramientas visibles más recursos y prompts compartidos, usando el tokenizador cl100k_base (codificación GPT-4/GPT-3.5). Para la matriz completa (superficies meta e individual, todos los modos GITLAB_MCP_META_PARAM_SCHEMA), consulta Token Footprint Reference.

Configuración predeterminada: con GITLAB_MCP_TOOL_SURFACE sin establecer o GITLAB_MCP_TOOL_SURFACE=dynamic, GITLAB_MCP_CAPABILITY_SURFACE=full, GITLAB_MCP_META_PARAM_SCHEMA=opaque y GITLAB_MCP_TIER sin establecer (detectado, respaldo free), el servidor usa la superficie dinámica find/execute. Usa GITLAB_MCP_TOOL_SURFACE=meta solo cuando quieras explícitamente meta-herramientas de dominio; usa GITLAB_MCP_TOOL_SURFACE=individual solo cuando tu cliente pueda manejar el catálogo completo de herramientas.

Las filas usan el catálogo base de Community Edition a menos que la columna de Nivel indique lo contrario. GITLAB_MCP_TIER controla qué acciones están disponibles; los niveles superiores exponen más herramientas y, por lo tanto, más acciones alcanzables.

Compatibilidad

Probado con: VS Code + GitHub Copilot, Claude Desktop, Claude Code, Cursor, Windsurf, IDE de JetBrains, Zed, Kiro, Cline. Consulta la Compatibility Matrix completa.

Evaluación de uso de herramientas por modelos de IA

El proyecto incluye un evaluador automatizado para la calidad MCP orientada a modelos, y actualmente no publica ningún resultado. Cada cifra que esta sección solía llevar ha sido retirada, incluido el 99.5% de éxito agregado con el que este README encabezaba.

Fueron retiradas porque la medición no medía lo que afirmaba. Una estructura alimentaba el estímulo que se le daba al modelo, el entorno en el que actuaba, el evaluador que lo calificaba y el informe al mismo tiempo, por lo que partes del corpus colocaban la llamada esperada en el prompt que el evaluador luego verificaba, las correcciones se hacían desde una clave de respuestas que el arnés proporcionaba, y el evaluador comparaba nombres de parámetros en lugar de sus valores. Una ejecución no podía fallar por las razones que se suponía que debía detectar. Las tablas tal como estaban por última vez se pueden leer en el commit 4587cbfb3; el relato de lo que estaba mal en ellas se conserva en AI Model Evaluation Results.

El reemplazo se está construyendo como un paquete etiquetado bajo test/e2e/ en el arnés de extremo a extremo, que ya mantiene separados el estímulo, el entorno y el registro. Los números regresan aquí cuando ese arnés los produzca.

Retirado. La tabla dinámica CE publicada aquí, actualizada por última vez desde una ejecución de Docker con fecha 20260627-232303, se puede leer en el commit 4587cbfb3 y no se reproduce porque la medición detrás de ella no era sólida.

Documentación

La documentación completa está en jmrp.io/docs/gitlab-mcp-server. Usa este mapa para la referencia de fuente de verdad sobre un área específica:

Preguntas frecuentes

Compilación desde el código fuente

git clone https://github.com/jmrplens/gitlab-mcp-server.git
cd gitlab-mcp-server
make build

La imagen de contenedor publicada es ghcr.io/jmrplens/gitlab-mcp-server:latest. Consulta la Guía de desarrollo para compilación cruzada, Docker Compose y pautas de contribución.

Política de privacidad

El servidor se ejecuta completamente en tu máquina y no tiene telemetría, análisis ni backend propio — los datos fluyen solo entre tu cliente MCP y la instancia de GitLab que configures (más una verificación opcional de actualización de binario firmado contra GitHub Releases). Tu token se usa únicamente para autenticar solicitudes de GitLab y nunca se registra. Detalles completos: PRIVACY.md.

Contribuciones ascendentes

Este servidor está construido sobre las API REST y GraphQL de GitLab, sobre client-go y sobre el SDK de MCP Go. Cuando compilarlo revela una brecha en uno de ellos, la corrección va ascendente en lugar de quedarse como solución alternativa aquí, para que todos los demás usuarios de esos proyectos también la reciban:

• client-go: campos de respuesta que GitLab envía y que las estructuras del SDK no modelaban, encontrados al contrastar cada estructura con lo que un GitLab en ejecución realmente envía, y correcciones como un pánico al decodificar un problema sin id (solicitudes de fusión).
• GitLab: documentación de API y anotaciones de respuesta corregidas donde discrepaban con lo que la API envía, una corrección para que una identidad GPG revocada ya no verifique confirmaciones, y adiciones propuestas como cancelar una fusión automática (solicitudes de fusión).
• SDK de MCP Go: correcciones de conformidad de protocolo en torno a la cancelación, la negociación de versión de protocolo y el protocolo de inicio (solicitudes de extracción).

Cada brecha se rastrea en docs/development/upstream-bugs.md: el problema o solicitud de fusión ascendente, si se ha fusionado y en qué versión, y la solución alternativa que este servidor mantiene hasta que se publique.

Contribuciones y seguridad

• Contribuciones: consulta CONTRIBUTING.md para pautas de desarrollo, nombres de ramas, convenciones de confirmación y el proceso de PR.
• Seguridad: consulta SECURITY.md para la política de seguridad y el informe de vulnerabilidades.
• Código de conducta: consulta CODE_OF_CONDUCT.md (Contributor Covenant v2.1).

Espejo del repositorio: GitHub es el repositorio canónico. Hay un espejo de solo lectura disponible en GitLab.com para su descubrimiento; abre las contribuciones en GitHub.

Mantenido por José M. Requena Plens · Página del proyecto · Instancia alojada: mcp.jmrp.io/gitlab