Primeros pasos

Documentación para desarrolladores

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

Pon en marcha GitLab MCP Server en menos de 5 minutos.

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.

Descarga

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 (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

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)
META_TOOLS	No	Selector booleano heredado: true para meta-herramientas o false para herramientas individuales (por defecto true)
TOOL_SURFACE	No	Selector explícito del catálogo: meta, individual, dynamic, dynamic-2 o dynamic-3
CAPABILITY_SURFACE	No	Selector del catálogo de recursos y prompts: full o minimal (por defecto full)
GITLAB_ENTERPRISE	No	true para habilitar herramientas Premium/Ultimate (por defecto false)
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: meta es el catálogo consolidado por defecto, individual expone cada herramienta por separado, dynamic y dynamic-3 seleccionan la superficie actual de bajo consumo con tres herramientas, y dynamic-2 selecciona la comparación experimental find/execute. META_TOOLS sigue funcionando para configuraciones heredadas (true equivale a meta, false equivale a individual), pero se recomienda tratarlo como obsoleto 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

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"
      }
    }
  }
}

Roo Code

Abre la barra lateral de Roo Code → haz clic en el icono de servidores MCP → Edit Global MCP (configuración global) o Edit Project MCP (crea .roo/mcp.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/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, habilita el catálogo Enterprise/Premium con GITLAB_ENTERPRISE=true en modo stdio o --enterprise/autodetección en modo HTTP. 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 meta-herramientas — en lugar de registrar cientos de herramientas individuales (hasta 1011 en GitLab.com Enterprise/Premium), las consolida en 32 meta-herramientas por dominio (47 en Enterprise/Premium autoalojado, 48 en GitLab.com Enterprise/Premium con Orbit) que cubren el 100% de la funcionalidad.

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_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 de tres herramientas, y TOOL_SURFACE=dynamic-2 está disponible como variante experimental find/execute.

Combina el modo dinámico con CAPABILITY_SURFACE=minimal para mantener solo workspace roots y omitir recursos y prompts opcionales cuando necesites el contexto MCP inicial más pequeño.

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