Ir al contenido
GitLab MCP Server

Binario nativo

Cada release publica un binario autocontenido por plataforma: Linux, macOS y Windows, en amd64 y arm64, compilado por GoReleaser con CGO_ENABLED=0 y -trimpath como ejecutable independiente de la posición y con la versión y el commit grabados dentro. Sin runtime, sin bibliotecas compartidas, sin contenedor; en Linux el binario necesita aun así el cargador dinámico de glibc, así que en sistemas con musl como Alpine usa la imagen Docker. Esta página cubre los dos scripts de instalación, la descarga manual, cómo comprobar lo que has descargado, dónde guardar el archivo y cómo reemplazarlo más adelante.

Script de instalación

Sección titulada «Script de instalación»

Los dos scripts hacen las mismas cuatro cosas: detectar la plataforma, descargar el archivo correspondiente de la última GitHub Release, verificar su SHA-256 contra el checksums.txt de esa misma release y copiarlo a un directorio del usuario. La verificación falla de forma segura: una discrepancia, una entrada ausente o un checksums.txt que no se puede descargar abortan la instalación en lugar de saltarse la comprobación. Como checksums.txt viene de la misma release que el binario, los dos scripts comprueban además una firma cuando pueden: con cosign instalado verifican checksums.txt.sigstore.json contra el workflow de release de este repositorio, fijado a la versión que se instala, y piden a la CLI gh la atestación de procedencia de compilación siempre que eso no haya verificado nada. Un verificador que se ejecutó y dijo que no aborta; un verificador que no pudo ejecutarse solo avisa, salvo que REQUIRE_SIGNATURE=1 lo convierta también en fatal.

Ventana de terminal
curl -fsSL https://raw.githubusercontent.com/jmrplens/gitlab-mcp-server/main/scripts/install.sh | sh

El script necesita curl o wget, además de sha256sum o shasum. Traduce x86_64 a amd64 y aarch64 a arm64, rechaza cualquier otro sistema o arquitectura (en Windows te remite al instalador de PowerShell), e instala el archivo con modo 0755 como $HOME/.local/bin/gitlab-mcp-server. Si ya hay un binario en esa ruta lo elimina primero, de modo que volver a ejecutarlo sobre un servidor en marcha no falla con “Text file busy”. Si $HOME/.local/bin no está en tu PATH, el script lo avisa e imprime la línea export PATH=... que debes añadir.

Antes de descargar nada resuelve latest a la etiqueta que nombra en ese momento, así que la comprobación de firma de más abajo queda fijada a la versión que se instala. El wget de BusyBox, el que trae Alpine, no puede seguir esa redirección; el script lo avisa y acepta en su lugar cualquier etiqueta de release del repositorio.

VariablePor defectoEfecto
INSTALL_DIR$HOME/.local/binDirectorio de destino
VERSIONlatestEtiqueta de la release a instalar, por ejemplo v3.2.0
REPOjmrplens/gitlab-mcp-serverRepositorio de GitHub desde el que descargar
REQUIRE_SIGNATUREsin definir1 aborta salvo que se verifique una firma o una atestación
ALLOW_UNVERIFIEDsin definir1 omite toda verificación, checksum y firma por igual, bajo tu responsabilidad (la salida en un sistema sin herramienta SHA-256)
FETCH_ATTEMPTS3Intentos por descarga antes de rendirse
FETCH_RETRY_DELAY2Segundos entre esos intentos

Definir a la vez REQUIRE_SIGNATURE=1 y ALLOW_UNVERIFIED=1 se rechaza en lugar de resolverse en un sentido u otro: piden cosas opuestas. Las variables van delante de sh, que es el proceso que ejecuta el script:

Ventana de terminal
curl -fsSL https://raw.githubusercontent.com/jmrplens/gitlab-mcp-server/main/scripts/install.sh | VERSION=v3.2.0 INSTALL_DIR=/usr/local/bin sh

Qué decide la comprobación de firma

Sección titulada «Qué decide la comprobación de firma»

Cada descarga se intenta hasta FETCH_ATTEMPTS veces, con FETCH_RETRY_DELAY segundos entre intentos, cuando no obtiene una respuesta utilizable. Un 404 o un 410 no se reintenta: el servidor ya ha dicho que el archivo no está.

Con cosign instalado, los scripts verifican checksums.txt.sigstore.json contra el workflow de release en la etiqueta que se instala. A la CLI gh se le pregunta siempre que eso no haya verificado nada, no solo cuando falta cosign, porque la atestación de procedencia de compilación vive en el almacén propio de GitHub y sigue siendo comprobable cuando el bundle es el archivo que ha desaparecido. Como gh tiene que preguntar a GitHub, los scripts comprueban antes que puede hacerlo (gh auth status): un gh que no llega a GitHub no ha emitido ningún veredicto y solo avisa, mientras que un gh que llegó a GitHub y rechazó el binario aborta.

ResultadoEfecto
cosign o gh verificanLa instalación sigue
cosign rechaza checksums.txtAborta
gh llega a GitHub y no encuentra ninguna atestación válidaAborta
cosign está instalado, la release no sirve checksums.txt.sigstore.json (un 404) y nada más se ha verificadoAborta
El bundle de la firma no se pudo descargar en absoluto, tras los reintentosAviso; REQUIRE_SIGNATURE=1 aborta
gh está instalado pero no llega a GitHubAviso; REQUIRE_SIGNATURE=1 aborta
No están instalados ni cosign ni ghAviso; REQUIRE_SIGNATURE=1 aborta

La cuarta fila es la razón por la que en una máquina con cosign no se puede colar nada borrando un solo archivo del release: todas las releases desde que empezó la firma publican el bundle, así que su ausencia no es una release antigua, sino el único archivo que quien reemplazó a la vez el binario y checksums.txt tendría que eliminar también. Una descarga que nunca volvió es un hecho distinto y se notifica como tal: no dice nada de si la release está firmada, así que avisa en lugar de afirmar que no lo está.

Descarga manual

Sección titulada «Descarga manual»

La última release incluye estos archivos:

PlataformaArchivo
Linux (x86_64)gitlab-mcp-server-linux-amd64
Linux (ARM64)gitlab-mcp-server-linux-arm64
macOS (universal)gitlab-mcp-server-darwin-all
macOS (Intel)gitlab-mcp-server-darwin-amd64
macOS (Apple Silicon)gitlab-mcp-server-darwin-arm64
Windows (x86_64)gitlab-mcp-server-windows-amd64.exe
Windows (ARM64)gitlab-mcp-server-windows-arm64.exe
Integridadchecksums.txt (los binarios, sus SBOM y los avisos), checksums.txt.sigstore.json, y un SBOM SPDX por binario, <archivo>.sbom.json
LicenciasTHIRD_PARTY_NOTICES, a partir de la primera release posterior a 3.1.0
Claude Desktopgitlab-mcp-server-darwin.mcpb, -windows.mcpb o -linux.mcpb (uno por sistema operativo, a partir de la primera release posterior a 3.1.0), y gitlab-mcp-server.mcpb para los tres (en todas las releases); consulta Claude Desktop

gitlab-mcp-server-darwin-all es un binario universal (arm64 y amd64 en un solo archivo), producido para la extensión de Claude Desktop para macOS porque su manifiesto solo puede elegir un archivo por sistema operativo, no por arquitectura. En macOS puedes usarlo o usar el archivo de una sola arquitectura; los tres aparecen en checksums.txt.

Dos formas de URL cubren todos los archivos: releases/latest/download/<archivo> resuelve siempre a la release más nueva, y releases/download/v<versión>/<archivo> fija una concreta.

Ventana de terminal
# Última release
curl -fsSLO https://github.com/jmrplens/gitlab-mcp-server/releases/latest/download/gitlab-mcp-server-linux-amd64


# Una versión fijada
curl -fsSLO https://github.com/jmrplens/gitlab-mcp-server/releases/download/v3.2.0/gitlab-mcp-server-linux-amd64

Hacerlo ejecutable (Linux/macOS)

Sección titulada «Hacerlo ejecutable (Linux/macOS)»

La descarga llega sin el bit de ejecución. Actívalo y mueve el archivo a un directorio de tu PATH, quitando el sufijo de plataforma para que el comando sea gitlab-mcp-server, igual que en el resto de canales:

Ventana de terminal
chmod +x gitlab-mcp-server-*
sudo mv gitlab-mcp-server-linux-amd64 /usr/local/bin/gitlab-mcp-server

Sin sudo, ~/.local/bin/gitlab-mcp-server funciona igual de bien; es donde lo deja el script de instalación.

En Windows, renombra el archivo a gitlab-mcp-server.exe y colócalo en una carpeta que esté en tu PATH, o referéncialo por su ruta completa desde la configuración del cliente.

Verifica lo que has descargado

Sección titulada «Verifica lo que has descargado»

Los scripts de instalación ya comparan la descarga con checksums.txt, y comprueban su firma cuando cosign o gh están instalados. Hecho a mano, esa comprobación más la firma del archivo de checksums son dos comandos. checksums.txt lista el SHA-256 de los siete binarios, de sus SBOM y, a partir de la primera release posterior a 3.1.0, de THIRD_PARTY_NOTICES, y checksums.txt.sigstore.json es una firma keyless de Cosign sobre ese archivo, hecha por el workflow de release con la identidad OIDC de GitHub, así que no hay ninguna clave que distribuir.

  1. Descarga checksums.txt y checksums.txt.sigstore.json de la misma release que el binario.

  2. Verifica la firma. La identidad es el workflow de release en la etiqueta que has descargado:

    Ventana de terminal
    cosign verify-blob \
      --bundle checksums.txt.sigstore.json \
      --certificate-identity "https://github.com/jmrplens/gitlab-mcp-server/.github/workflows/release.yml@refs/tags/v3.2.0" \
      --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
      checksums.txt

    --certificate-identity-regexp "^https://github.com/jmrplens/gitlab-mcp-server/" en lugar de la identidad exacta acepta cualquier etiqueta firmada por los workflows de este repositorio. En ambos casos la salida esperada es Verified OK.

  3. Comprueba el binario contra la lista firmada:

    Ventana de terminal
    # Linux
    sha256sum --check --ignore-missing checksums.txt
    

    # macOS (shasum no tiene --ignore-missing; filtra la línea relevante primero)
    grep "$(ls gitlab-mcp-server-*)" checksums.txt | shasum -a 256 -c
    Ventana de terminal
    # Windows: las dos cadenas hexadecimales deben coincidir (mayúsculas aparte)
    (Get-FileHash .\gitlab-mcp-server-windows-amd64.exe -Algorithm SHA256).Hash
    Select-String gitlab-mcp-server-windows-amd64.exe .\checksums.txt

    Salida esperada en Linux y macOS: gitlab-mcp-server-linux-amd64: OK, o el nombre de tu archivo.

Si cualquiera de los dos pasos falla, no ejecutes el archivo. El recorrido completo, incluida la instalación de Cosign, está en Verificación de la integridad del release.

Las releases se publican solo cuando todos sus archivos están adjuntos y atestados, y los paquetes de npm, PyPI y NuGet y la fórmula de Homebrew se construyen a partir de esos archivos publicados después de comprobar su firma; Cómo llega una release a cada canal recoge el orden.

Dónde colocarlo

Sección titulada «Dónde colocarlo»
  • Por usuario, sin sudo: ~/.local/bin en Linux y macOS (el valor por defecto del script), %LOCALAPPDATA%\Programs\gitlab-mcp-server en Windows (el valor por defecto del script de PowerShell).
  • Para todo el sistema: /usr/local/bin en Linux y macOS.

Los clientes que arrancan desde el escritorio en lugar de desde una shell no siempre heredan el PATH de tu shell. Si un cliente dice que no encuentra gitlab-mcp-server, pon la ruta absoluta en su configuración en lugar del nombre a secas.

Comprueba que arranca

Sección titulada «Comprueba que arranca»
Ventana de terminal
gitlab-mcp-server --version

imprime gitlab-mcp-server 3.2.0 (commit: <commit>) para la release actual. Arrancar el binario sin argumentos en una terminal, o hacerle doble clic en Windows, sin GITLAB_URL y GITLAB_TOKEN definidos imprime una breve pantalla de primera ejecución que nombra los dos valores que necesita y espera a que pulses Enter; un cliente MCP nunca la ve, porque habla con el servidor por tuberías. No hay asistente de configuración.

Configura tu cliente

Sección titulada «Configura tu cliente»

La entrada stdio mínima es la ruta al binario y el token. Añade GITLAB_URL a env solo para una instancia autogestionada:

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

Con Claude Code el registro en sí es un comando que no nombra ningún token, claude mcp add gitlab -- gitlab-mcp-server, porque el servidor lee ~/.gitlab-mcp-server.env para lo que no tenga ya en su entorno:

Ventana de terminal
# Pide el token sin mostrarlo, así que queda fuera del historial de la shell
printf 'GitLab token: ' && read -rs t && printf 'GITLAB_TOKEN=%s\n' "$t" > ~/.gitlab-mcp-server.env && unset t && echo
chmod 600 ~/.gitlab-mcp-server.env
claude mcp add gitlab -- gitlab-mcp-server

Añade GITLAB_URL=https://gitlab.example.com al mismo archivo para GitLab autoalojado. Las pestañas por cliente, incluido el mapa servers de VS Code con la petición enmascarada del token, están en el Inicio rápido.

Actualizar y desinstalar

Sección titulada «Actualizar y desinstalar»

El binario nunca se actualiza a sí mismo. Para actualizar, vuelve a ejecutar el script de instalación, que reemplaza el archivo in situ tras verificar el checksum nuevo, o descarga el archivo más nuevo y sobrescribe el antiguo. VERSION=v3.2.0 (o $env:VERSION en Windows) fija una release concreta cuando necesitas quedarte en ella.

Para desinstalar, borra el archivo: rm ~/.local/bin/gitlab-mcp-server (o donde lo hayas colocado) en Linux y macOS; en Windows, borra %LOCALAPPDATA%\Programs\gitlab-mcp-server y quita esa carpeta de tu PATH de usuario, que el script añadió y nunca elimina. Después quita la entrada gitlab de la configuración de tu cliente.

Compilar desde el código fuente

Sección titulada «Compilar desde el código fuente»

El código se compila con la versión de Go que indica el archivo go.mod (hoy la 1.27) y nada más:

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

make build genera dist/gitlab-mcp-server (.exe en Windows) para la máquina en la que se ejecuta, y make build-all compila de forma cruzada los seis destinos de la release en el mismo directorio. Un binario compilado así no lleva firma ni atestación de procedencia, porque las genera el workflow de release. La guía de desarrollo cubre los tests, las comprobaciones de análisis y el resto del flujo para contribuir.

Mantenido por GitHubLinkedInMastodonGoogle ScholarTodos los proyectos