Configuración

Documentación para desarrolladores

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

GitLab MCP Server se configura mediante variables de entorno en modo stdio y flags de CLI en modo HTTP. Esta página cubre todas las opciones de configuración.

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

Esta debe establecerse para que el servidor arranque en modo stdio:

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
META_TOOLS	true	Selector booleano heredado: true para meta-herramientas o false para herramientas individuales. Usa TOOL_SURFACE para superficies dinámicas
TOOL_SURFACE	—	Selector explícito del catálogo: meta, individual, dynamic, dynamic-2 o dynamic-3. Cuando se establece, sobrescribe META_TOOLS
CAPABILITY_SURFACE	full	Selector del catálogo de recursos y prompts: full conserva el catálogo completo; minimal mantiene solo gitlab://workspace/roots y desactiva recursos y prompts opcionales
META_PARAM_SCHEMA	opaque	Estrategia de esquema de entrada para meta-herramientas: opaque (por defecto), compact (~5x) o full (~10x). El esquema por acción siempre es accesible vía el recurso gitlab://schema/meta/{tool}/{action}
GITLAB_ENTERPRISE	false	Habilitar herramientas Enterprise/Premium en modo stdio. En modo HTTP, --enterprise puede forzar el catálogo; si se omite, la edición se autodetecta por entrada token+URL
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)
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

Consejo

El modo meta-herramientas (META_TOOLS=true) es altamente recomendado. Agrupa las herramientas por dominio (p. ej., gitlab_issue gestiona list, get, create, update, delete) lo que reduce el uso de tokens y mejora la precisión de selección de herramientas por la IA.

Usa TOOL_SURFACE=dynamic para el catálogo visible estable más pequeño: solo se exponen gitlab_search_tools, gitlab_describe_tools y gitlab_execute_tool, respaldadas por el mismo catálogo canónico de acciones de GitLab. TOOL_SURFACE=dynamic-3 selecciona explícitamente esa misma superficie actual de tres herramientas para configuraciones fijadas. Usa TOOL_SURFACE=dynamic-2 solo cuando quieras intencionadamente la variante experimental find/execute.

Consulta Conjunto de herramientas dinámico para el flujo buscar, describir y ejecutar.

Para despliegues dinámicos donde los recursos y prompts dominan el contexto inicial, usa CAPABILITY_SURFACE=minimal. Mantiene gitlab://workspace/roots para descubrimiento de proyectos y omite recursos opcionales, recursos de meta-schema, guías de flujo y prompts. Con CAPABILITY_SURFACE=minimal, usa gitlab_describe_tools para recuperar los schemas de acciones dinámicas en línea. El valor por defecto sigue siendo full.

Autoactualización

Variable	Predeterminado	Descripción
AUTO_UPDATE	true	Comportamiento de autoactualización: true (aplicar al iniciar), 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 descarga pre-inicio (rango: 5s–10m)

Opciones de administración

Variable	Predeterminado	Descripción
YOLO_MODE	false	Omitir confirmaciones de acciones destructivas (no recomendado)
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
META_TOOLS=true
GITLAB_ENTERPRISE=false
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
--meta-tools	true	Habilitar modo meta-herramientas. Establécelo a false para herramientas individuales
--tool-surface	—	Selector explícito del catálogo: meta, individual, dynamic, dynamic-2 o dynamic-3. Sobrescribe --meta-tools
--capability-surface	full	Selector del catálogo de recursos y prompts: full o minimal
--enterprise	false	Forzar herramientas Enterprise/Premium si se establece; omítelo para autodetectar CE/EE por entrada token+URL
--read-only	false	Modo solo lectura
--safe-mode	false	Intercepta herramientas modificantes y devuelve una vista previa JSON en lugar de ejecutarlas
--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
--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 descarga pre-inicio (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 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.