GitLab MCP Server

Conecta tu asistente de IA a GitLab para que pueda revisar merge requests, clasificar 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 toda la API 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. No hay que recordar IDs de proyecto, endpoints de API ni JSON.

«Revisa la merge request !15: ¿es seguro fusionarla?» · «¿Por qué falló el último pipeline?» · «Lista los issues abiertos asignados a mí» · «Genera notas de versión 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 comandos de una sola línea de claude mcp add y los valores predeterminados — está en llms.txt (no se necesita asistente interactivo).

Instalación en 60 segundos

Elige una opción. Cada vía termina con que escribas un prompt a tu asistente.

Instalación con un clic

Cada botón registra el servidor basado en Docker (descarga la imagen automáticamente en la primera ejecución; necesitas Docker instalado). La fila de Claude Desktop en cambio descarga una extensión de escritorio .mcpb nativa (macOS universal + Windows, sin Docker): ábrela con Claude Desktop y rellena los ajustes. ¿Necesitas un token? Crea un token de acceso personal con el ámbito api. ¿GitLab autogestionado? Añade la 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 --http=false

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

# 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

¿GitLab autogestionado? Añade --env GITLAB_URL=https://gitlab.example.com (y --env GITLAB_SKIP_TLS_VERIFY=true para certificados autofirmados).

Configuración guiada (cualquier cliente, sin flags que recordar)

El binario incluye un asistente de configuración que recoge tu token de GitLab y configura tu cliente MCP por ti — ideal si prefieres no editar JSON:

gitlab-mcp-server --setup

Detecta automáticamente VS Code, Claude Desktop, Claude Code, Cursor y Windsurf, y escribe la configuración adecuada. En Windows, haz doble clic en el .exe para iniciarlo.

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

Binario nativo (mcpServers de Claude Desktop, Cursor, etc.):

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

VS Code (.vscode/mcp.json, ten en cuenta servers + type):

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

Variante Docker: sustituye "command"/"args" por:

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

Cline (VS Code): abre la barra lateral de Cline → icono de servidores MCP → Editar MCP global, o edita directamente el archivo de configuración:

• macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

• Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

• Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

Cline usa la estructura mcpServers mostrada arriba para el binario nativo.

Para un despliegue HTTP compartido y de larga duración en lugar del stdio por usuario, consulta Modo servidor HTTP.

Pruébalo sin instalar nada (endpoint alojado)

Una instancia pública está disponible en https://mcp.jmrp.io/gitlab: no hay nada que instalar, ni más cuenta que tu propio token de GitLab. Apunta hacia ella cualquier cliente MCP compatible con HTTP:

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

PRIVATE-TOKEN es obligatorio y viaja en cada petición: nunca se almacena en el servidor. GITLAB-URL es opcional y su valor predeterminado es https://gitlab.com; establécelo para llegar a otra instancia (debe ser accesible desde Internet público).

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

El endpoint es HTTP streamable sin estado en la superficie dynamic predeterminada: POST es el transporte, GET sobre él responde 405 por diseño, y https://mcp.jmrp.io/gitlab/health responde 200 con {"status":"ok",…}. Un despliegue HTTP autoalojado también puede ejecutarse con --auth-mode=oauth --gitlab-url=https://gitlab.com --public-url=https://mcp.example.com (ambos son obligatorios: OAuth necesita una instancia fija y el origen accesible externamente por el que RFC 9728 identifica el recurso), donde los clientes descubren GitLab como 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 app 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.

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

Related MCP server: mcp-gitlab-jira

Por qué este servidor

• GitLab en lenguaje natural. La IA traduce «¿es seguro fusionar el MR !15?» a las llamadas de 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 de CI/CD, seguridad, administración, tokens y más.

• Bajo consumo de tokens por defecto. La superficie dynamic por defecto expone solo 2 herramientas (find + execute) mientras llega al catálogo completo, por lo que cabe en la ventana de contexto de cualquier cliente. (Huella de tokens →)

• Probado con modelos reales. Un evaluador automatizado ejecuta Anthropic, Google, OpenAI y Qwen contra instancias de GitLab en vivo: 99.5% de éxito agregado en miles de operaciones. (Resultados →)

• Seguro por diseño. Modo de solo lectura, modo seguro (vista previa dry-run de cada mutación), opciones TLS para GitLab autoalojado y controles continuos de calidad/seguridad de SonarCloud.

• Se ejecuta en cualquier lugar. Un único binario estático o contenedor; Windows, Linux y macOS; amd64 y arm64; stdio (escritorio) y HTTP (remoto).

• 45 recursos MCP (datos de solo lectura: proyectos, issues, pipelines, MRs, ramas, miembros, el manifiesto gitlab://tools consciente de la superficie y guías de mejores prácticas de flujo de trabajo). 26 tipos de objeto único también son suscribibles.

• 37 prompts MCP (revisión de código, estado del pipeline, evaluación de riesgos, notas de release, standup, análisis, auditoría y más).

• 4 asistentes de elicitación (creación interactiva de issues/MR/releases/proyectos).

• 4 capacidades MCP (completions, progress, elicitation y suscripciones a recursos: notificaciones en vivo de resources/updated, atendidas mediante polling) y 51 iconos de herramientas (50 iconos de dominio más el logotipo del proyecto) para la identificación visual en clientes MCP.

• Paginación en cada endpoint de listado con metadatos completos.

Superficies de herramientas

El servidor puede exponer GitLab de tres formas, controladas por TOOL_SURFACE. La opción por defecto no requiere configuración.

El número de herramientas escala con tu edición de GitLab (GITLAB_TIER); los niveles superiores exponen más acciones. Consulta Dynamic Toolset y Meta-Tools Reference para ver el modelo de clasificación, las salvaguardas de seguridad y los catálogos completos. Para ejecuciones dynamic en las que los recursos dominan el contexto, establece 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 META_PARAM_SCHEMA), consulta Token Footprint Reference.

Configuración por defecto: con TOOL_SURFACE sin definir o TOOL_SURFACE=dynamic, CAPABILITY_SURFACE=full, META_TOOLS sin definir, META_PARAM_SCHEMA=opaque y GITLAB_TIER sin definir (detectado, fallback free), el servidor usa la superficie dynamic find/execute. Usa TOOL_SURFACE=meta solo cuando quieras explícitamente meta-tools de dominio; usa TOOL_SURFACE=individual solo cuando tu cliente pueda manejar el catálogo de herramientas completo.

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

Compatibilidad

Probado con: VS Code + GitHub Copilot, Claude Desktop, Claude Code, Cursor, Windsurf, JetBrains IDEs, Zed, Kiro, Cline. Consulta la matriz de compatibilidad completa.

Evaluación del uso de herramientas por modelos de IA

El proyecto incluye un evaluador automatizado de la

Documentación

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

Preguntas frecuentes

Sí. Establece GITLAB_URL en la URL de tu instancia. Cuando se omite GITLAB_URL, el modo stdio usa https://gitlab.com. Los certificados TLS autofirmados son compatibles mediante GITLAB_SKIP_TLS_VERIFY=true.

Cuando lo ejecutas tú mismo — localmente mediante stdio, o en tu propia infraestructura mediante HTTP — todas las llamadas a la API van directamente a tu instancia de GitLab. La única solicitud que sale a cualquier otro lugar es la comprobación de actualizaciones contra GitHub Releases, que está activada por defecto y se desactiva con AUTO_UPDATE=false.

La excepción es el endpoint alojado: usar https://mcp.jmrp.io/gitlab significa que tu token y cada solicitud pasan por esa máquina. Allí no se almacena nada, pero es un servidor de otra persona, por eso la sección del endpoint alojado recomienda seguir usándolo localmente.

Consulta PRIVACY.md para saber exactamente qué envía la comprobación de actualizaciones, y SECURITY.md para conocer el modelo de seguridad.

Sí. Establece GITLAB_READ_ONLY=true para deshabilitar todas las herramientas de modificación (crear, actualizar, eliminar). Solo estarán disponibles las operaciones de lectura.

Alternativamente, establece GITLAB_SAFE_MODE=true para un modo de simulación (dry-run): las herramientas de modificación permanecen visibles pero devuelven una vista previa JSON estructurada en lugar de ejecutarse. Útil para auditar, entrenar o revisar lo que haría un asistente de IA.

Tanto la Community Edition (CE) como la Enterprise Edition (EE). Establece GITLAB_TIER=premium o GITLAB_TIER=ultimate en modo stdio para habilitar herramientas adicionales para las funciones Premium/Ultimate (métricas DORA, vulnerabilidades, cumplimiento, etc.); déjalo sin establecer para detectar el nivel desde la licencia de la instancia (valor por defecto free). En modo HTTP, --tier puede forzar el nivel; de lo contrario, se detecta por cada entrada del pool de token+URL a partir de la licencia.

El servidor incluye lógica de reintento con retroceso (backoff) para los límites de tasa de la API de GitLab. Los errores se clasifican como transitorios (reintentables) o permanentes, con pistas accionables en los mensajes de error.

Cualquier cliente compatible con MCP: VS Code + GitHub Copilot, Claude Desktop, Cursor, Claude Code, Windsurf, JetBrains IDEs, Zed, Kiro y otros. El asistente de configuración integrado puede configurar automáticamente la mayoría de los clientes.

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 conocer las pautas de compilación cruzada, Docker Compose y contribución.

Política de privacidad

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

Contribución y seguridad

• Contribución: consulta CONTRIBUTING.md para conocer las pautas de desarrollo, la nomenclatura de ramas, las convenciones de commits y el proceso de PR.

• Seguridad: consulta SECURITY.md para conocer la política de seguridad y la notificación 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 facilitar su descubrimiento; por favor, abre las contribuciones en GitHub.

Recuento de archivos

Funciones

Proporciones que vale la pena señalar

Patrones de código

Proyecto

Salón de la fama

Porque sí

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