Primeros pasos

GitLab MCP Server conecta tu asistente de IA con GitLab en menos de cinco minutos. Instalas el servidor — como imagen Docker, binario nativo o mediante un botón de un clic —, le proporcionas un Personal Access Token de GitLab y lo registras con un cliente compatible con MCP como VS Code, Claude Desktop, Cursor o Claude Code. Esta guía cubre todas las vías de instalación y cómo verificar la conexión.

GitLab MCP Server expone más de 1.000 operaciones de GitLab — 865 herramientas en CE y hasta 1091 en GitLab.com — a través de tres modos de herramientas (dinámico, meta-herramienta e individual), de modo que un único token desbloquea toda la superficie de la API de GitLab.

Antes de comenzar, asegúrate de tener:

1. Una instancia de GitLab — GitLab.com, CE autoalojado o EE
2. Un Personal Access Token (PAT) con el scope api
3. Un cliente de IA compatible con MCP — VS Code + Copilot, Claude Desktop, Cursor o Claude Code

1. Ve a GitLab → Preferences → Access Tokens
2. Crea un nuevo token con el scope api
3. Copia el token — lo necesitarás para la configuración

Elige una: cada vía termina contigo escribiendo un prompt a tu asistente. Cada canal tiene además su propia página con todos los comandos y los pasos de verificación, actualización y desinstalación; empieza por Elige una vía si no tienes claro cuál te encaja. Para la referencia completa por cliente, consulta Configuración manual más abajo.

Registran un servidor basado en Docker (descarga la imagen en la primera ejecución; necesitas Docker instalado). VS Code te pide el token; Cursor / LM Studio / Kiro añaden un marcador YOUR_GITLAB_TOKEN que debes sustituir.

Para Claude Desktop, descarga en su lugar la extensión de escritorio .mcpb — una instalación nativa en un clic (macOS universal + Windows) sin Docker y con el token guardado en el llavero del sistema.

Todos los botones ejecutan la imagen del contenedor; la página Docker cubre sus etiquetas, el modo HTTP y cómo actualizarla.

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

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

El comando de registro nunca lleva el token. -e GITLAB_TOKEN sin valor reenvía la variable desde el entorno que Claude Code le da a docker, así que expórtala donde lances el cliente (tu perfil de shell lo hace duradero) o añádela después al bloque env de la entrada.

Cualquier otro canal se registra igual en cuanto gitlab-mcp-server está en tu PATH, y ahí el token va en un archivo que el servidor lee:

echo 'GITLAB_TOKEN=glpat-xxxx' > ~/.gitlab-mcp-server.env
claude mcp add gitlab -- gitlab-mcp-server

Publicado como @jmrp.io/gitlab-mcp-server. npm descarga solo el binario precompilado de tu plataforma: no compila nada, y nada se ejecuta durante la instalación, así que funciona con --ignore-scripts y tras un proxy.

npx -y @jmrp.io/gitlab-mcp-server

Apunta cualquier cliente MCP a npx sin instalar nada:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@jmrp.io/gitlab-mcp-server"],
      "env": { "GITLAB_URL": "https://gitlab.com", "GITLAB_TOKEN": "glpat-…" }
    }
  }
}

Publicado como jmrplens-gitlab-mcp-server con el mismo modelo que uv y ruff: cada wheel de plataforma lleva el binario nativo, el instalador lo coloca en la ruta de scripts como el propio comando gitlab-mcp-server, y no se ejecuta Python cuando corre el servidor. Las wheels de Linux necesitan glibc; en sistemas musl como Alpine, usa la imagen Docker en su lugar.

uvx jmrplens-gitlab-mcp-server

{
  "mcpServers": {
    "gitlab": {
      "command": "uvx",
      "args": ["jmrplens-gitlab-mcp-server"],
      "env": { "GITLAB_URL": "https://gitlab.com", "GITLAB_TOKEN": "glpat-…" }
    }
  }
}

Publicado en NuGet.org como gitlab-mcp-server, una herramienta .NET con la disposición que el SDK de .NET 10 usa para las herramientas que distribuyen un ejecutable nativo: un paquete puntero nombra un paquete por identificador de runtime, cada uno con el mismo binario, y el SDK lo ejecuta directamente. Necesita el SDK de .NET 10 o superior, y no se ejecuta código .NET una vez arranca el servidor. Los paquetes de Linux necesitan glibc; en sistemas musl como Alpine, usa la imagen Docker en su lugar.

dnx gitlab-mcp-server

{
  "mcpServers": {
    "gitlab": {
      "command": "dnx",
      "args": ["gitlab-mcp-server"],
      "env": { "GITLAB_URL": "https://gitlab.com", "GITLAB_TOKEN": "glpat-…" }
    }
  }
}

Los argumentos destinados al servidor van después de -- (dnx gitlab-mcp-server -- --version), porque dnx lee sus propias opciones en cualquier posición de la línea; y dnx instala la herramienta sin preguntar cuando su entrada estándar no es una terminal, que es como la arranca un cliente, así que la configuración no necesita ningún flag adicional.

Instala el binario en tu PATH y lo registra. Las actualizaciones vienen de lo que lo instaló (brew upgrade, winget upgrade o volver a ejecutar el script); el servidor no se actualiza a sí mismo.

# Linux/macOS (script; comprueba el SHA-256 contra checksums.txt antes de instalar)
curl -fsSL https://raw.githubusercontent.com/jmrplens/gitlab-mcp-server/main/scripts/install.sh | sh

echo 'GITLAB_TOKEN=glpat-xxxx' > ~/.gitlab-mcp-server.env
claude mcp add gitlab -- gitlab-mcp-server

Homebrew, winget y el instalador de PowerShell dejan el mismo binario en tu PATH; cada uno tiene su propia página con el comando, dónde queda el binario y cómo actualizarlo y desinstalarlo:

¿GitLab autoalojado? Añade GITLAB_URL=https://gitlab.example.com al mismo archivo (y GITLAB_MCP_SKIP_TLS_VERIFY=true para certificados autofirmados), un CLAVE=valor por línea.

Hay una instancia pública en https://mcp.jmrp.io/gitlab — nada que instalar, sin más cuenta que tu propio token de GitLab. Apunta cualquier cliente MCP con soporte HTTP a ella:

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

El endpoint funciona en modo OAuth, así que la credencial viaja en Authorization: Bearer — un token de acceso personal de GitLab sirve ahí, verificado igual que uno de OAuth. Viaja en cada petición y nunca se guarda en el servidor. Un cliente que hable el flujo OAuth no necesita cabecera alguna: el 401 lleva un desafío RFC 9728 que sigue para autorizar en el navegador. PRIVATE-TOKEN es la cabecera del modo legacy y aquí no se acepta; la instancia está fijada a https://gitlab.com, así que GITLAB-URL se ignora. Un token read_api se acepta y recibe una superficie de herramientas de solo lectura.

Hay dos páginas que lo ponen aún más fácil. La ficha del servidor enumera el catálogo completo sin credencial alguna y trae configuración lista para copiar para Claude Code, Cursor y VS Code — incluido el client ID de OAuth que esos clientes necesitan. El inspector del navegador llama a ese mismo endpoint en modo solo lectura desde una pestaña: inicias sesión con OAuth, eliges una herramienta y lees el JSON-RPC en crudo que devuelve — sin instalar nada.

Es la forma más rápida de probar el servidor, y la forma correcta de usarlo a diario sigue siendo en local (cualquier opción de arriba), por un motivo concreto: tu token y todas tus peticiones pasan por la máquina de otra persona. Ejecutarlo en local mantiene ambos en tu ordenador — la única opción sensata para una instancia autogestionada privada.

El endpoint es streamable HTTP sin estado sobre la superficie dynamic por defecto: POST es el transporte y un GET autenticado responde 405 por diseño; sin credencial, cualquier método responde 401 con el desafío RFC 6750 que sigue un cliente OAuth — un curl a secas que recibe 401 es el endpoint funcionando, no fallando. https://mcp.jmrp.io/gitlab/health no necesita credencial y responde 200 con {"status":"ok",…}. Es uno de los servidores listados en mcp.jmrp.io, un directorio de los servidores MCP que mantiene el autor, cada uno accesible en su propio endpoint; https://mcp.jmrp.io/servers.json es esa misma lista para clientes automáticos.

Es un servicio personal, mantenido por una sola persona y ofrecido tal cual: sin SLA, sin canal de soporte y sin garantía de que siga igual la semana que viene. No añade cuota propia — cada llamada se descuenta de los límites de la propia GitLab.com, con tu token. Y avanza por sí solo, normalmente a la última release, así que lo que sirve nunca es una versión fijada.

¿Prefieres colocar el binario tú mismo? Descarga el último binario para tu plataforma desde la página de GitHub Releases:

chmod +x gitlab-mcp-server-*

Opcionalmente, muévelo a un directorio en tu PATH:

sudo mv gitlab-mcp-server-linux-amd64 /usr/local/bin/gitlab-mcp-server

Comprobar la descarga contra checksums.txt y su firma Cosign, actualizar y desinstalar están en la página Binario nativo.

No hay asistente de configuración. La configuración MCP va en el propio archivo JSON de tu cliente, que es lo que documenta Configuración manual más abajo, y un asistente que escribe un dotfile en una máquina no podía ponerla ahí.

Ejecutar el binario en una terminal sin GITLAB_TOKEN y GITLAB_URL definidos (basta con que falte una de las dos), o hacer doble clic sobre él, imprime qué es el servidor, los dos valores que necesita y dónde está documentado el JSON de cada cliente, y después espera a que pulses Enter para que una ventana abierta con doble clic en Windows no se cierre antes de que puedas leerla. Un cliente MCP nunca ve esa pantalla: un cliente conecta tuberías en lugar de una terminal, así que el servidor arranca con normalidad.

Este repositorio incluye un manifest Agent Plugins 1.0 (plugin.json en la raíz y la configuración MCP mcp.json), más el manifest legado de Open Plugins (.plugin/plugin.json) para hosts antiguos, para que el servidor se instale en un solo paso en un host compatible (Cursor, Claude Code, VS Code, OpenCode). Suministrar el token es un paso aparte, explicado más abajo:

# Cursor / Claude Code (cuando lo soporte tu versión)
/plugin install jmrplens/gitlab-mcp-server

El plugin ejecuta la imagen Docker publicada ghcr.io/jmrplens/gitlab-mcp-server:latest mediante docker run -i --rm y no pasa ninguna opción de transporte, por lo que necesitas Docker instalado y en ejecución. La imagen deduce el transporte a partir de la entrada estándar y -i es lo que coloca ahí una tubería, así que mantén el -i si copias la configuración Docker en VS Code u otro cliente stdio; sin él, el contenedor recibe /dev/null, inicia un listener HTTP y el cliente espera indefinidamente una respuesta stdio a initialize.

GITLAB_TOKEN es el único valor obligatorio; GITLAB_URL solo importa para una instancia autogestionada. La configuración incluida reenvía ambas al contenedor, pero tu host tiene que ponerlas antes en el entorno del plugin: la §9.1 de Agent Plugins permite al cliente «heredar, omitir o sanear» las variables del entorno ambiente, y la spec no define ninguna forma portable de que un plugin referencie un secreto, así que el token no puede viajar dentro del propio mcp.json. Si el servidor devuelve un fallo de autorización, define GITLAB_TOKEN como documente tu host, o añádelo al bloque env del mcp.json local del plugin instalado. La tabla completa de variables reenviadas está en la página Plugins de agente.

Instala el plugin y después edita el mcp.json local del plugin instalado (habitualmente en .agents/plugins/gitlab-mcp-server/) para sustituir el command / args de Docker por la ruta a un binario de cualquiera de los canales anteriores. La página Plugins de agente tiene el archivo exacto que escribir, y por qué un marcador ${GITLAB_TOKEN} en él llegaría al servidor de forma literal. Para despliegues HTTP en segundo plano, no uses una entrada stdio: ejecuta la imagen en modo HTTP y configura el cliente con type: "http" y una URL como http://localhost:8080/mcp, como describe Modo servidor HTTP.

GITLAB_URL usa https://gitlab.com por defecto; añádela solo para instancias GitLab autogestionadas.

Si prefieres configurar manualmente, elige tu cliente de IA:

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

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

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

echo 'GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx' > ~/.gitlab-mcp-server.env
chmod 600 ~/.gitlab-mcp-server.env

claude mcp add gitlab \
  --transport stdio \
  -- /ruta/a/gitlab-mcp-server

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

{
  "context_servers": {
    "gitlab": {
      "command": "/ruta/a/gitlab-mcp-server",
      "args": [],
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

{
  "mcpServers": {
    "gitlab": {
      "command": "/ruta/a/gitlab-mcp-server",
      "args": [],
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

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

En lugar de colocar secretos en archivos de configuración del cliente, puedes ponerlos en un archivo dotenv:

GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

Añade GITLAB_URL=https://gitlab.example.com para GitLab autogestionado.

El servidor lee ~/.gitlab-mcp-server.env para los valores que su entorno no traiga ya. Para guardar el archivo en otro sitio, nómbralo por ruta absoluta en GITLAB_MCP_ENV_FILE.

Un .env en el directorio de trabajo no se lee. Tu editor fija ese directorio en el espacio de trabajo que abrió, así que el archivo llega con el repositorio y no de tu mano; si existe uno, el arranque lo nombra en el log junto con las claves que pretendía definir. Consulta Configuración para el orden de carga completo.

Para despliegues en equipo, puedes ejecutar el servidor en modo HTTP donde cada usuario se autentica con su propio token:

./gitlab-mcp-server --http --http-addr=0.0.0.0:8080 --gitlab-url=https://gitlab.com

Cada cliente se conecta vía HTTP y proporciona su propio token de GitLab. Consulta Modo servidor HTTP para más detalles.

Para gestión de tokens sin configuración manual, usa el modo OAuth. Los usuarios autorizan a través del navegador — no se requiere copiar ni distribuir tokens:

./gitlab-mcp-server --http --gitlab-url=https://gitlab.com --auth-mode=oauth --public-url=https://mcp.example.com

Los clientes MCP que soportan OAuth 2.1 (VS Code, Claude Code) descubren el servidor de autorización automáticamente vía /.well-known/oauth-protected-resource. Consulta docs/guides/oauth-app-setup.md para crear la Aplicación OAuth de GitLab requerida.

Si te conectas a una instancia de GitLab autoalojada (Community Edition o Enterprise Edition), la configuración es la misma — solo asegúrate de que GITLAB_URL apunte a tu instancia interna:

GITLAB_URL=https://gitlab.internal.company.com
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

Muchas instancias autoalojadas usan certificados autofirmados o de CA interna. Si ves errores x509: certificate signed by unknown authority, añade:

GITLAB_MCP_SKIP_TLS_VERIFY=true

GITLAB_URL=https://gitlab.internal.company.com
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

GITLAB_URL=https://gitlab.company.com:8443
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

GITLAB_URL=http://gitlab.local:3000
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

GITLAB_URL=https://gitlab.internal.company.com
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
GITLAB_MCP_SKIP_TLS_VERIFY=true

Tanto GitLab CE (gratuito) como EE (Premium/Ultimate) son totalmente compatibles. Para funciones exclusivas de EE como métricas DORA, épicas y gestión de vulnerabilidades, establece GITLAB_MCP_TIER=premium (o GITLAB_MCP_TIER=ultimate) en modo stdio, o usa --tier=premium/--tier=ultimate en modo HTTP. Cuando se omite, el tier se detecta desde GET /license (por defecto free). La variable de entorno heredada GITLAB_ENTERPRISE=true sigue respetándose en modo stdio por compatibilidad, pero está deprecada; el modo HTTP solo lee --tier, y no existe ningún flag --enterprise. Consulta Configuración para todas las opciones disponibles.

Una vez configurado, abre tu cliente de IA y pregunta:

¿Quién soy en GitLab?

El servidor debería devolver tu perfil de usuario de GitLab, confirmando que la conexión funciona. También puedes probar:

Lista mis merge requests asignadas

Muestra los pipelines recientes en my-project

¡Si ves resultados, todo está listo!

Por defecto, el servidor funciona en modo dinámico find/execute con gitlab_find_action y gitlab_execute_action. Cada operación de GitLab es una acción del catálogo con un ID canónico domain.action: el asistente localiza la que necesita (con su schema exacto de parámetros) y después la ejecuta. Crear un issue tiene esta forma:

{
  "tool": "gitlab_execute_action",
  "arguments": {
    "action": "issue.create",
    "params": {
      "project_id": "my-group/my-project",
      "title": "Fix login redirect"
    }
  }
}

Establece GITLAB_MCP_TOOL_SURFACE=meta para usar 34 meta-herramientas por dominio (51 en Enterprise/Premium autoalojado, 52 en GitLab.com Enterprise/Premium con Orbit) que cubren la misma funcionalidad mediante despachadores consolidados por dominio. En lugar de herramientas separadas gitlab_issue_list, gitlab_issue_create y gitlab_issue_update (la forma de GITLAB_MCP_TOOL_SURFACE=individual), hay una única herramienta gitlab_issue con un parámetro action: la misma llamada va a gitlab_issue como { "action": "create", "params": { ... } }. Las meta-herramientas solo aceptan action y params en el nivel superior, así que los parámetros van anidados en params en ambas superficies.

Esto es transparente para ti: tu cliente de IA se encarga del enrutamiento. Solo pregunta de forma natural, “crea un issue para el bug del login”, y en la superficie dinámica predeterminada el asistente localiza issue.create y la ejecuta; con GITLAB_MCP_TOOL_SURFACE=meta elige la meta-herramienta gitlab_issue y la acción create.

• Configuración — Ajusta las variables de entorno y funciones opcionales
• Conjunto de herramientas dinámico — Cómo la superficie find/execute predeterminada descubre y ejecuta cualquier operación
• Meta-herramientas — Los despachadores consolidados por dominio de GITLAB_MCP_TOOL_SURFACE=meta
• Arquitectura — Comprende cómo funciona el servidor internamente
• Referencia de herramientas — Explora todas las herramientas disponibles por dominio

Preguntas frecuentes

¿Qué scope de token necesita GitLab MCP Server?

GitLab MCP Server necesita un Personal Access Token con el scope `api` para acceso completo de lectura y escritura a la API REST y GraphQL de GitLab. Para una configuración de solo lectura, crea un token con el scope `read_api` y establece GITLAB_MCP_READ_ONLY=true, lo que desactiva todas las herramientas de escritura. Crea tokens en GitLab → Preferences → Access Tokens.

¿Cómo conecto a una instancia de GitLab autogestionada?

Apunta GITLAB_URL a tu instancia, por ejemplo GITLAB_URL=https://gitlab.example.com. GITLAB_URL usa https://gitlab.com por defecto, así que solo la estableces para instancias autogestionadas Community o Enterprise Edition. Si la instancia usa un certificado autofirmado o de CA interna, establece también GITLAB_MCP_SKIP_TLS_VERIFY=true para omitir la verificación del certificado en una red de confianza.

¿Qué modo de herramientas usa GitLab MCP Server por defecto?

Por defecto, GitLab MCP Server funciona en modo dinámico, que expone solo dos herramientas — gitlab_find_action y gitlab_execute_action — para mantener pequeño el contexto del cliente de IA sin dejar de alcanzar cualquier operación de GitLab. Establece GITLAB_MCP_TOOL_SURFACE=meta para meta-herramientas consolidadas por dominio, o GITLAB_MCP_TOOL_SURFACE=individual para una herramienta por operación.

¿Por qué mi cliente de IA no se conecta?

Una conexión fallida suele significar que GitLab MCP Server no puede alcanzar GitLab o no puede autenticarse. Comprueba que GITLAB_URL es correcta y accesible desde tu máquina, que el token tiene el scope api (o read_api en modo solo lectura) y no ha caducado, y que los certificados autofirmados se gestionan estableciendo GITLAB_MCP_SKIP_TLS_VERIFY=true.