Primeros pasos

Documentación para desarrolladores

Para la referencia técnica completa, consulta docs/getting-started.md en el repositorio.

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 — 847 herramientas en CE y hasta 1071 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.

Requisitos previos

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

Crear un personal access token

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

Consejo

Para configuraciones de solo lectura, puedes usar un token con scope read_api y habilitar GITLAB_READ_ONLY=true. Esto desactiva todas las herramientas de escritura.

Instalación rápida

Elige una — cada vía termina contigo escribiendo un prompt a tu asistente. Para la referencia completa por cliente, consulta Configuración manual más abajo.

Botones de un clic

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.

Claude Code (claude mcp add)

Docker (sin instalar nada — 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

Instalador de una línea (binario nativo)

Instala el binario en tu PATH y lo registra. Las actualizaciones las gestiona el auto-update integrado del binario (o Homebrew, que fija su propia fórmula con checksums).

# 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 (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 autoalojado? Añade --env GITLAB_URL=https://gitlab.example.com (y --env GITLAB_SKIP_TLS_VERIFY=true para certificados autofirmados).

¿Prefieres una vía guiada?

El asistente de configuración integrado recoge tu token y configura tu cliente por ti — sin editar JSON. Ejecuta gitlab-mcp-server --setup tras instalar el binario.

Descarga

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

Plataforma	Binario
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
Claude Desktop	gitlab-mcp-server.mcpb — consulta Extensión para Claude Desktop

Hacerlo ejecutable (Linux/macOS)

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

Asistente de configuración

La forma más fácil de configurar clientes stdio locales es el asistente de configuración integrado:

gitlab-mcp-server --setup

El asistente:

• Solicitará tu URL de GitLab y token
• Cargará cualquier configuración existente para que puedas conservar o cambiar valores previos
• Configurará clientes MCP soportados
• Escribirá ~/.gitlab-mcp-server.env sin guardar secretos en archivos JSON de cliente

Nota

El asistente configura solo clientes stdio. Ofrece interfaces Web, TUI y CLI. Consulta Asistente de configuración para modos, clientes soportados, opciones avanzadas y comportamiento de reconfiguración.

Instalar como Open Plugin (Cursor / Claude Code)

Este repositorio incluye un manifest Open Plugins v1.0.0 (.plugin/plugin.json) y una configuración MCP referenciada (mcp.json) para que el servidor se pueda instalar en un solo paso en cualquier host compatible (Cursor, Claude Code, OpenCode):

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

El plugin usa la imagen Docker publicada ghcr.io/jmrplens/gitlab-mcp-server:latest mediante docker run -i --rm, por lo que necesitas Docker instalado y en ejecución. El mcp.json incluido está configurado para clientes MCP stdio y pasa --http=false después del nombre de la imagen para sobrescribir el modo HTTP predeterminado de la imagen Docker. Mantén esa opción si copias la configuración Docker en VS Code u otro cliente stdio; de lo contrario, el contenedor iniciará un listener HTTP y el cliente esperará indefinidamente una respuesta stdio a initialize.

Variables de entorno requeridas

El host debe proporcionar estas variables antes de habilitar el plugin:

Variable	Obligatoria	Descripción
GITLAB_URL	No	URL de la instancia GitLab. Por defecto usa https://gitlab.com; establécela para instancias autogestionadas
GITLAB_TOKEN	Sí	Personal Access Token (glpat-...)
GITLAB_SKIP_TLS_VERIFY	No	true para certificados autofirmados (por defecto false)
TOOL_SURFACE	No	Selector canónico del catálogo: dynamic, meta o individual (por defecto dynamic)
META_TOOLS	No	Selector de compatibilidad deprecado: true mapea a meta, false mapea a individual, y dynamic al valor equivalente de TOOL_SURFACE
CAPABILITY_SURFACE	No	Selector del catálogo de recursos y prompts: full o minimal (por defecto full)
GITLAB_TIER	No	Edición de GitLab: free/ce, premium o ultimate. Cuando se omite, se detecta desde GET /license (por defecto free). Reemplaza al booleano deprecado GITLAB_ENTERPRISE.
GITLAB_READ_ONLY	No	true para deshabilitar herramientas de escritura (por defecto false)
GITLAB_SAFE_MODE	No	true para previsualizar entradas de herramientas mutantes (por defecto false)
LOG_LEVEL	No	debug, info, warn, error (por defecto info)

TOOL_SURFACE tiene precedencia sobre META_TOOLS cuando ambos están definidos. Usa TOOL_SURFACE en configuraciones nuevas: dynamic es la superficie predeterminada de bajo consumo con find/execute, meta expone meta-herramientas consolidadas por dominio e individual expone cada herramienta por separado. META_TOOLS sigue funcionando por compatibilidad, pero se recomienda tratarlo como deprecado frente al selector explícito.

¿Prefieres binario nativo en lugar de Docker?

La spec de Open Plugins arranca automáticamente cada entrada de la configuración MCP referenciada, así que la configuración incluida usa Docker stdio por portabilidad. Para despliegues HTTP en segundo plano, no uses una entrada de cliente stdio; ejecuta la imagen Docker en modo HTTP y configura el cliente MCP con type: "http" y una URL como http://localhost:8080/mcp. Consulta Modo servidor HTTP.

Si prefieres el binario nativo, instala el plugin, localiza el directorio del plugin instalado gitlab-mcp-server desde la interfaz de plugins de tu host o la salida de instalación, y después edita su mcp.json local (habitualmente en .agents/plugins/gitlab-mcp-server/) para sustituir el command / args de Docker por la ruta al binario que hayas descargado desde GitHub Releases:

{
  "mcpServers": {
    "gitlab": {
      "command": "/usr/local/bin/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "${GITLAB_TOKEN}"
      }
    }
  }
}

Configuración manual

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

Si prefieres configurar manualmente, elige tu cliente de IA:

VS Code / Copilot

Crea o edita .vscode/mcp.json en la raíz de tu workspace:

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

Almacenamiento seguro de tokens

Usa variables de entrada de VS Code para evitar almacenar el token en texto plano:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitlab-token",
      "description": "GitLab Personal Access Token",
      "password": true
    }
  ],
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "/ruta/a/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "${input:gitlab-token}"
      }
    }
  }
}

Claude Desktop

La vía más fácil

Claude Desktop también se instala con un clic mediante la extensión de escritorio .mcpb — sin editar JSON y con el token guardado en el llavero del sistema.

Edita ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Cursor

Crea o edita .cursor/mcp.json en la raíz de tu proyecto:

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

Claude Code

Añade el servidor usando la CLI:

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

Luego establece el token requerido:

export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"

Establece GITLAB_URL aquí solo para instancias autogestionadas, o crea un archivo .env en tu directorio de trabajo con las variables anteriores.

Windsurf

Edita ~/.codeium/windsurf/mcp_config.json:

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

JetBrains

1. Abre Settings → Tools → AI Assistant → MCP Servers
2. Haz clic en + Add y selecciona stdio
3. Establece el comando a /ruta/a/gitlab-mcp-server
4. Añade GITLAB_TOKEN = glpat-xxxxxxxxxxxxxxxxxxxx
5. Añade GITLAB_URL solo para instancias autogestionadas
6. Haz clic en OK y reinicia el IDE

Zed

Edita tu settings.json de Zed y añade:

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

Kiro

Crea o edita .kiro/mcp.json en la raíz de tu proyecto:

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

Cline

Abre la barra lateral de Cline → haz clic en el icono de servidores MCP → Edit Global MCP, o edita el archivo de configuración directamente:

• 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

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

Uso de un archivo .env

En lugar de colocar secretos en archivos de configuración del cliente, puedes usar un archivo .env:

.env

GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

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

El servidor carga .env desde el directorio de trabajo actual automáticamente. Consulta Configuración para el orden de carga completo.

Modo HTTP

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.

Modo OAuth (recomendado para producción)

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

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.

Precaución

Los clientes deben configurarse con el clientId de la Aplicación OAuth de GitLab y el scope api. Sin clientId, los clientes recurren al Registro Dinámico de Clientes (DCR) que asigna el scope mcp en lugar de api, causando que la mayoría de las operaciones fallen. Consulta Modo servidor HTTP para ejemplos por cliente.

GitLab autoalojado

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:

.env

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

Certificados autofirmados

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

.env

GITLAB_SKIP_TLS_VERIFY=true

Precaución

Omitir la verificación TLS desactiva la validación de certificados para todas las solicitudes a la API de GitLab. Úsalo solo para instancias internas donde confías en la red. Para producción, configura el almacén de CA de confianza de tu sistema en su lugar.

Configuraciones comunes

HTTPS interno

.env

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

Puerto personalizado

.env

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

HTTP (solo dev)

.env

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

Precaución

Las conexiones HTTP transmiten tokens en texto plano. Usa HTTP solo para instancias de desarrollo local.

Cert. autofirmado

.env

GITLAB_URL=https://gitlab.internal.company.com
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
GITLAB_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_TIER=premium (o GITLAB_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). El booleano heredado GITLAB_ENTERPRISE=true y el flag --enterprise siguen funcionando por compatibilidad, pero están deprecados. Consulta Configuración para todas las opciones disponibles.

Verificar la configuración

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!

Precaución

Si obtienes errores de conexión, comprueba:

• Que GITLAB_URL es correcta y accesible desde tu máquina
• Que el token tiene el scope api
• Para certificados autofirmados, establece GITLAB_SKIP_TLS_VERIFY=true

Entendiendo las meta-herramientas

Por defecto, el servidor funciona en modo dinámico find/execute con gitlab_find_action y gitlab_execute_action. Establece TOOL_SURFACE=meta para usar 32 meta-herramientas por dominio (49 en Enterprise/Premium autoalojado, 50 en GitLab.com Enterprise/Premium con Orbit) que cubren la misma funcionalidad mediante despachadores consolidados por dominio.

Por ejemplo, en lugar de herramientas separadas gitlab_list_issues, gitlab_create_issue, gitlab_close_issue, hay una única herramienta gitlab_issue con un parámetro action:

{
  "tool": "gitlab_issue",
  "arguments": {
    "action": "create",
    "project": "my-group/my-project",
    "title": "Fix login redirect"
  }
}

Esto es transparente para ti — tu cliente de IA maneja el enrutamiento automáticamente. Solo pregunta de forma natural: “crea un issue para el bug del login” y el LLM selecciona la meta-herramienta y acción correctas.

Consejo

Las meta-herramientas reducen el overhead de tokens en un 96% mientras preservan la funcionalidad completa. Consulta Meta-herramientas para la referencia completa.

Para el catálogo visible estable más pequeño, establece TOOL_SURFACE=dynamic. El servidor expone solo gitlab_find_action y gitlab_execute_action, respaldadas por el mismo catálogo canónico de acciones de GitLab.

Combina el modo dinámico con CAPABILITY_SURFACE=minimal para mantener solo workspace roots y gitlab://tools, y omitir recursos opcionales, guías y prompts cuando necesites el contexto MCP inicial más pequeño. Dynamic conserva schemas inline mediante gitlab_find_action.

Preguntas frecuentes de configuración

¿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_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_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 TOOL_SURFACE=meta para meta-herramientas consolidadas por dominio, o 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_SKIP_TLS_VERIFY=true.

Próximos pasos

• Configuración — Ajusta las variables de entorno y funciones opcionales
• Meta-herramientas — Entiende cómo se organizan las herramientas y descubre todas las operaciones disponibles
• Arquitectura — Comprende cómo funciona el servidor internamente
• Referencia de herramientas — Explora todas las herramientas disponibles por dominio