Configuración

Documentación para desarrolladores

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

GitLab MCP Server casi no necesita nada para arrancar. En modo stdio — el predeterminado que usan las integraciones con IDE — solo estableces dos cosas: con qué instancia de GitLab hablar (GITLAB_URL) y un personal access token para hacerlo (GITLAB_TOKEN). En GitLab.com hasta la URL es opcional, porque GITLAB_URL usa https://gitlab.com por defecto, así que un único GITLAB_TOKEN basta; apunta GITLAB_URL a tu propio host para instancias autogestionadas. En modo HTTP el servidor no guarda credencial alguna — cada cliente envía su propio token (y, opcionalmente, su propia URL de GitLab) en cada petición. Todo lo demás en esta página es opcional y viene con un valor predeterminado seguro.

El modo stdio lee su configuración de variables de entorno o de un archivo .env; el modo HTTP lee flags de CLI. Esta página cubre las opciones que la mayoría de usuarios necesita; consulta la referencia de variables y la referencia CLI del repositorio para las tablas exhaustivas.

Orientación rápida

Modo stdio (por defecto) — configura mediante variables de entorno o un archivo .env. Este es el modo utilizado por las integraciones con IDE (VS Code, Cursor, Claude Desktop, etc.).

Modo HTTP (--http) — configura mediante flags de CLI. Usado para despliegues compartidos/remotos (Docker, Fly.io, Kubernetes). Ir a Flags del modo HTTP.

Variables requeridas

GitLab MCP Server requiere exactamente una variable para arrancar en modo stdio — el resto son opcionales y usan valores predeterminados seguros:

Variable	Descripción	Ejemplo
GITLAB_TOKEN	Personal Access Token con scope api	glpat-xxxxxxxxxxxxxxxxxxxx

Opciones principales

Variable	Predeterminado	Descripción
GITLAB_URL	https://gitlab.com	URL base de la instancia GitLab. Establécela para instancias autogestionadas
GITLAB_SKIP_TLS_VERIFY	false	Omitir verificación de certificados TLS para certificados autofirmados
TOOL_SURFACE	dynamic	Selector canónico del catálogo: dynamic, meta o individual
META_TOOLS	heredado	Selector de compatibilidad deprecado. true mapea a meta, false mapea a individual, y los valores dynamic mapean al TOOL_SURFACE equivalente cuando TOOL_SURFACE no está definido
CAPABILITY_SURFACE	full	Selector del catálogo de recursos y prompts: full conserva el catálogo completo; minimal mantiene el manifiesto gitlab://tools, y desactiva recursos opcionales, prompts y guías de flujo
META_PARAM_SCHEMA	opaque	Estrategia de esquema de entrada para meta-herramientas: opaque (por defecto), compact (6.5x el tamaño opaque) o full (11.9x). Solo afecta schemas de meta-herramientas en tools/list
GITLAB_TIER	(autodetectado)	Selector de edición de GitLab: free/ce, premium o ultimate. Cuando se establece, se usa tal cual; cuando se omite, se detecta desde GET /license (por defecto free). El tier restringe las herramientas Enterprise/Premium y poda entradas de esquema por campo mediante pruneSchemaFieldsByTier (ver internal/tools/action_catalog.go)
GITLAB_READ_ONLY	false	Desactivar todas las herramientas de escritura (crear, actualizar, eliminar)
GITLAB_SAFE_MODE	false	Devolver vista previa JSON estructurada en lugar de ejecutar herramientas de escritura (modo dry-run)
EMBEDDED_RESOURCES	true	Incrustar URIs MCP canónicas gitlab:// en resultados de herramientas get; usa false para clientes que no toleren bloques de contenido duplicados
EXCLUDE_TOOLS	—	Lista de herramientas a excluir separadas por comas (ej., gitlab_delete_project,gitlab_admin)
GITLAB_IGNORE_SCOPES	false	Omitir detección automática de scopes del PAT — registrar todas las herramientas sin importar los scopes
LOG_LEVEL	info	Nivel de verbosidad del log: debug, info, warn, error
EVAL_SURFACE_ENTERPRISE	false	cmd/eval_mcp_surfaces: ejecuta el conjunto de casos enterprise además del corpus base
EVAL_SURFACE_CASE_SET	ce	cmd/eval_mcp_surfaces: selector del conjunto de casos — ce (solo CE) o all (CE+Enterprise)
EVAL_SURFACE_FIXTURE_SMOKE	false	cmd/eval_mcp_surfaces: limita la ejecución a los casos fixture-smoke (comprobación rápida)

Consejo

El modo dinámico (TOOL_SURFACE=dynamic) es el predeterminado y el catálogo visible de menor consumo. Expone gitlab_find_action y gitlab_execute_action, mientras conserva el mismo catálogo canónico de acciones GitLab.

Usa TOOL_SURFACE=meta cuando un cliente o flujo de trabajo prefiera despachadores consolidados por dominio con parámetro action.

Consulta Conjunto de herramientas dinámico para el flujo find/execute.

Para despliegues dinámicos donde los recursos y prompts dominan el contexto inicial, usa CAPABILITY_SURFACE=minimal. Mantiene gitlab://tools para descubrir acciones, y omite recursos opcionales, prompts y guías de flujo. Esto no elimina los schemas del descubrimiento dinámico: usa gitlab_find_action para recuperar schemas exactos antes de llamar a gitlab_execute_action, o lee gitlab://tools/{id} para una entrada del manifiesto. El valor por defecto sigue siendo full; hoy no se expone un modo schemas-only.

Autoactualización

Variable	Predeterminado	Descripción
AUTO_UPDATE	true	Comportamiento de autoactualización: true (aplicar en segundo plano), check (solo notificar), false (deshabilitado)
AUTO_UPDATE_REPO	jmrplens/gitlab-mcp-server	Repositorio de GitHub para los assets de release
AUTO_UPDATE_INTERVAL	1h	Intervalo de comprobación periódica (solo modo HTTP)
AUTO_UPDATE_TIMEOUT	60s	Timeout de actualización de arranque/en segundo plano (rango: 5s–10m)

Opciones de administración

Variable	Predeterminado	Descripción
YOLO_MODE	false	Omitir confirmaciones de acciones destructivas (no recomendado)
AUTOPILOT	false	Igual que YOLO_MODE: omitir confirmaciones destructivas
GITLAB_MCP_ALLOWED_IMPORT_DIRS	—	Directorios adicionales, separados por la lista de rutas del sistema operativo, permitidos para archivos locales de importación de proyectos/grupos
RATE_LIMIT_RPS	0	Límite de velocidad por servidor en req/s (0 = desactivado)
RATE_LIMIT_BURST	40	Tamaño del bucket de tokens cuando RATE_LIMIT_RPS > 0

Archivo .env de ejemplo

.env

# Requeridas
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

# Opcionales
GITLAB_SKIP_TLS_VERIFY=false
TOOL_SURFACE=dynamic
GITLAB_TIER=free
GITLAB_READ_ONLY=false
GITLAB_SAFE_MODE=false
EXCLUDE_TOOLS=
GITLAB_IGNORE_SCOPES=false
LOG_LEVEL=info

# Autoactualización
AUTO_UPDATE=true

Para GitLab autogestionado, añade GITLAB_URL=https://gitlab.example.com.

Configuración de clientes

VS Code / Copilot

Crea .vscode/mcp.json en tu workspace:

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

Configuración segura del token usando variables de entrada de VS Code:

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

Consejo

La opción password: true oculta la entrada del token. VS Code lo solicitará una vez por sesión.

Claude Desktop

Edita claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Cursor

Crea .cursor/mcp.json en tu proyecto:

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

Claude Code

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

Establece las variables de entorno antes de iniciar:

export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"

Establece GITLAB_URL aquí solo para instancias autogestionadas.

O usa un archivo .env en el directorio de trabajo.

Continue

Añade a ~/.continue/config.yaml (o al .continue/config.yaml de tu workspace):

mcpServers:
  - name: gitlab
    command: /ruta/a/gitlab-mcp-server
    env:
      GITLAB_TOKEN: glpat-xxxxxxxxxxxxxxxxxxxx

Recarga la ventana de Continue tras editar la configuración. Consulta la documentación MCP de Continue para alternativas en modo HTTP y OAuth.

Windsurf

Edita ~/.codeium/windsurf/mcp_config.json (Cascade → Plugins → Configure):

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

Reinicia Windsurf o pulsa Refresh en el panel de Plugins para que se apliquen los cambios.

JetBrains AI

Los IDEs de JetBrains (IntelliJ IDEA, GoLand, PyCharm, etc.) con el plugin AI Assistant soportan servidores MCP en Settings → Tools → AI Assistant → Model Context Protocol.

Añade una entrada stdio apuntando al binario:

• Nombre: gitlab
• Comando: /ruta/a/gitlab-mcp-server
• Variables de entorno: GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

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

Alternativamente, crea .idea/mcp.json en la raíz del proyecto con la misma estructura JSON usada por VS Code / Cursor. Reinicia el IDE tras editar.

Flags del modo HTTP

Al ejecutar en modo HTTP (--http), la configuración usa flags de CLI en lugar de variables de entorno:

Flag	Predeterminado	Descripción
--http	false	Habilitar modo de transporte HTTP
--http-addr	:8080	Dirección y puerto de escucha
--gitlab-url	—	URL fija de la instancia de GitLab. Omítela para requerir GITLAB-URL en cada petición
--skip-tls-verify	false	Omitir verificación TLS
--tool-surface	dynamic	Selector canónico del catálogo: dynamic, meta o individual
--meta-tools	(sin definir)	Flag de compatibilidad deprecado. Usa --tool-surface=individual en lugar de --meta-tools=false
--meta-param-schema	opaque	Modo de schema para params de meta-herramientas: opaque, compact o full; solo afecta schemas de meta-herramientas
--capability-surface	full	Selector del catálogo de recursos y prompts: full o minimal; minimal mantiene el manifiesto gitlab://tools, y omite recursos opcionales, guías y prompts
--tier	(autodetectado)	Forzar la edición de GitLab: free/ce, premium o ultimate; omítelo para autodetectar CE/EE por entrada token+URL. Reemplaza al flag deprecado --enterprise
--read-only	false	Modo solo lectura
--safe-mode	false	Intercepta herramientas modificantes y devuelve una vista previa JSON en lugar de ejecutarlas
--embedded-resources	true	Incrustar URIs MCP canónicas en resultados de herramientas get
--exclude-tools	—	Herramientas a excluir separadas por comas
--ignore-scopes	false	Omitir detección de scopes del PAT
--max-http-clients	100	Máximo de sesiones de clientes simultáneas
--session-timeout	30m	Tiempo de espera de sesión inactiva
--http-idle-timeout	0 (desactivado)	Timeout de conexión inactiva del servidor HTTP. 0 (por defecto) desactiva el cierre por inactividad, de modo que --session-timeout es la vida efectiva; usa una duración positiva para reciclar conexiones antes
--auto-update	true	Modo de autoactualización
--auto-update-repo	jmrplens/gitlab-mcp-server	Repositorio de GitHub para releases
--auto-update-interval	1h	Intervalo de comprobación periódica de actualizaciones
--auto-update-timeout	60s	Tiempo de espera de actualización de arranque/en segundo plano (5s–10m)
--auth-mode	legacy	Modo de autenticación: legacy u oauth
--oauth-cache-ttl	15m	TTL de caché de identidad OAuth (1m–2h)
--revalidate-interval	15m	Intervalo de revalidación de token; 0 para desactivar (límite: 24h)
--rate-limit-rps	0	Límite de tasa por servidor para tools/call en req/s (0 = desactivado)
--rate-limit-burst	40	Tamaño del token bucket cuando --rate-limit-rps > 0
--trusted-proxy-header	—	Cabecera HTTP con la IP real del cliente para rate limiting detrás de proxies (ej. Fly-Client-IP, X-Forwarded-For)

Flags del evaluador de superficies (solo para cmd/eval_mcp_surfaces):

Flag	Predeterminado	Descripción
--max-output-retries	2	Reejecuta una tarea cuando falla únicamente por salida de tool-call mal formada
--case-set	ce	Selector del conjunto de casos: ce (solo CE) o all (CE+Enterprise)
--enterprise-case-set	false	Ejecuta el conjunto de casos enterprise además del corpus base
--fixture-smoke	false	Limita la ejecución a los casos fixture-smoke (comprobación rápida)

Flags generales (modos stdio y HTTP):

Flag	Predeterminado	Descripción
--shutdown	false	Terminar todas las instancias en ejecución y salir

Ejemplo:

# Instancia única de GitLab.com (URL fija para todos los clientes; reemplázala para GitLab autogestionado)
./gitlab-mcp-server \
  --http \
  --http-addr=0.0.0.0:8080 \
  --gitlab-url=https://gitlab.com \
  --max-http-clients=200 \
  --session-timeout=1h

# Multi-instancia (cada cliente especifica su URL de GitLab mediante la cabecera GITLAB-URL)
./gitlab-mcp-server \
  --http \
  --http-addr=0.0.0.0:8080

Orden de carga de la configuración

El servidor carga la configuración en el siguiente orden (las fuentes posteriores anulan las anteriores):

1. ~/.gitlab-mcp-server.env — Valores predeterminados a nivel de usuario (directorio home)
2. .env — Configuración a nivel de proyecto (directorio de trabajo actual)
3. Variables de entorno del sistema — Variables exportadas en el shell
4. Flags de CLI — Argumentos de línea de comandos (prioridad más alta)

Nota

En modo HTTP, GITLAB_TOKEN no se carga desde variables de entorno. Cada cliente proporciona su propio token mediante la petición HTTP. Los clientes pueden enviar una cabecera GITLAB-URL solo cuando el servidor arranca sin --gitlab-url.

Cuando --gitlab-url está configurado, es autoritativo y los valores GITLAB-URL enviados por clientes se ignoran y se registran. Otras opciones de política del servidor, incluido el tamaño de esquema (--meta-param-schema) y los límites de tasa (--rate-limit-rps, --rate-limit-burst), no se pueden sobreescribir por petición.

Certificados autofirmados

Para instancias de GitLab con certificados TLS autofirmados:

GITLAB_SKIP_TLS_VERIFY=true

Precaución

Usa esto solo en entornos de red confiables. Desactiva la verificación de certificados para todas las conexiones a la instancia de GitLab.

Modo solo lectura

Habilita GITLAB_READ_ONLY=true para restringir el servidor a operaciones de solo lectura. Todas las herramientas que crean, actualizan o eliminan recursos se desactivan. Esto es útil para:

• Entornos de auditoría y cumplimiento
• Servidores compartidos donde los usuarios solo deben consultar datos
• Tokens con scope read_api

Modo seguro

Habilita GITLAB_SAFE_MODE=true para interceptar las herramientas de escritura y devolver una vista previa JSON estructurada de lo que se ejecutaría, sin realizar la operación. Las herramientas de solo lectura funcionan normalmente. Esto es útil para:

• Revisar operaciones antes de ejecutarlas (dry-run)
• Entornos de formación donde se quiere ver el comportamiento de las herramientas
• Depurar parámetros de herramientas sin efectos secundarios

Nota

Si GITLAB_READ_ONLY=true también está configurado, tiene precedencia — las herramientas de escritura se desactivan completamente en lugar de mostrar una vista previa.

Preguntas frecuentes

¿Cuál es la configuración mínima?

En modo stdio, un único GITLAB_TOKEN con el scope api basta para arrancar — cualquier otra variable es opcional y usa un valor predeterminado seguro. GITLAB_URL usa https://gitlab.com por defecto, así que solo la estableces al conectar a una instancia autogestionada. Para una configuración de solo lectura, usa un token read_api y añade GITLAB_READ_ONLY=true. En modo HTTP no se configura ningún token en el servidor; cada cliente envía el suyo en cada petición.

stdio vs HTTP — ¿qué modo uso?

Usa el modo stdio (el predeterminado) para configuraciones locales de un solo usuario como integraciones con IDE (VS Code, Cursor, Claude Desktop); se configura mediante variables de entorno o un archivo .env. Usa el modo HTTP (--http) para despliegues compartidos o remotos como Docker, Fly.io o Kubernetes, donde la configuración usa flags de CLI y cada cliente se autentica con su propio token de GitLab en cada petición.

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

Establece GITLAB_URL con la URL base de tu instancia, por ejemplo GITLAB_URL=https://gitlab.example.com (en modo HTTP, usa el flag --gitlab-url). Si la instancia usa un certificado autofirmado o de CA interna, establece también GITLAB_SKIP_TLS_VERIFY=true (o --skip-tls-verify en modo HTTP), pero solo en una red de confianza — desactiva la verificación de certificados para todas las conexiones a GitLab.

¿Cómo elijo una superficie de herramientas (dynamic, meta o individual)?

Establece la variable TOOL_SURFACE (o el flag --tool-surface en modo HTTP). dynamic es la predeterminada y la de menor consumo de tokens: expone gitlab_find_action y gitlab_execute_action mientras mantiene cada acción de GitLab accesible a través del catálogo canónico de acciones. Elige meta cuando un cliente prefiere despachadores consolidados por dominio con un parámetro action, e individual para registrar una herramienta MCP por cada operación de GitLab.