cerngitlab-mcp

Servidor MCP de CERN GitLab

Un servidor MCP que conecta LLMs a CERN GitLab para descubrir código de HEP, documentación y ejemplos de análisis.

Características

15 herramientas MCP para buscar, explorar y analizar repositorios de CERN GitLab
Operación de doble modo — modos stdio (usuario único) y HTTP (multi-usuario)
Herramienta CLI (cerngitlab-cli) para uso directo desde la línea de comandos
Acceso público — funciona sin autenticación para repositorios públicos
Modo HTTP multi-usuario — autenticación CERN SSO + GitLab OAuth para despliegues centralizados; GitLab aplica todos los permisos de acceso de forma nativa
Enfocado en HEP — análisis de dependencias para ecosistemas Python y C++, detección binaria para archivos .root, búsqueda de issues
Robusto — limitación de tasa, reintentos con retroceso exponencial, manejo elegante de errores

Instalación

Requiere Python 3.10+.

Inicio rápido (recomendado)

No se necesita instalación — solo usa uvx para ejecutar directamente:

uvx cerngitlab-mcp

Desde PyPI

pip install cerngitlab-mcp

Desde el código fuente

git clone https://github.com/MohamedElashri/cerngitlab-mcp
cd cerngitlab-mcp
uv sync

Configuración

Todos los ajustes se configuran mediante variables de entorno con el prefijo CERNGITLAB_:

Variable	Predeterminado	Descripción
`CERNGITLAB_GITLAB_URL`	`https://gitlab.cern.ch`	URL de la instancia de GitLab
`CERNGITLAB_TOKEN`	(vacío)	Token de acceso personal (opcional, para modo stdio)
`CERNGITLAB_TIMEOUT`	`30`	Tiempo de espera HTTP en segundos
`CERNGITLAB_MAX_RETRIES`	`3`	Reintentos máximos para solicitudes fallidas
`CERNGITLAB_RATE_LIMIT_PER_MINUTE`	`300`	Límite de tasa de API
`CERNGITLAB_LOG_LEVEL`	`INFO`	Nivel de registro
`CERNGITLAB_DEFAULT_REF`	(vacío)	Rama o etiqueta Git predeterminada para búsqueda de código. Vacío usa el comportamiento de referencia predeterminado de GitLab.
`CERNGITLAB_HTTP_MODE`	(vacío)	Establece cualquier valor para auto-detectar el modo HTTP
`CERNGITLAB_HOST`	`0.0.0.0`	Dirección de enlace del servidor HTTP
`CERNGITLAB_PORT`	`8000`	Puerto de enlace del servidor HTTP
`CERNGITLAB_CERN_CLIENT_ID`	(vacío)	Modo HTTP — ID de cliente OAuth de CERN SSO
`CERNGITLAB_GITLAB_OAUTH_CLIENT_ID`	(vacío)	Modo HTTP — ID de cliente de la aplicación OAuth de GitLab
`CERNGITLAB_GITLAB_OAUTH_CLIENT_SECRET`	(vacío)	Modo HTTP — Secreto de cliente de la aplicación OAuth de GitLab
`CERNGITLAB_SERVER_BASE_URL`	`http://localhost:8000`	Modo HTTP — URL base pública (usada para el callback de OAuth)
`CERNGITLAB_SESSION_STORAGE_PATH`	`/tmp/cerngitlab/sessions`	Modo HTTP — Directorio para persistir archivos de sesión OAuth

Autenticación

El servidor funciona en dos modos:

Sin token — Acceso a todos los repositorios públicos. Suficiente para la mayoría del descubrimiento de código HEP.
Con token — Acceso adicional a proyectos internos/privados, búsqueda de código y páginas wiki.

Para crear un token:

Ve a https://gitlab.cern.ch/-/user_settings/personal_access_tokens
Crea un token con el alcance read_api
Establece CERNGITLAB_TOKEN=glpat-xxxxxxxxxxxx

Nota: La búsqueda de código (search_code), búsqueda de issues (search_issues) y wiki (get_wiki_pages) requieren autenticación en CERN GitLab.

Uso

Claude Desktop

Agrega a tu claude_desktop_config.json:

{
  "mcpServers": {
    "cerngitlab": {
      "command": "uvx",
      "args": ["cerngitlab-mcp"],
      "env": {
        "CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
      }
    }
  }
}

Nota para usuarios de macOS: Si ves un error sobre uvx no encontrado, es posible que necesites proporcionar la ruta absoluta. Claude Desktop no admite la expansión de ~ o $HOME.

Ejecuta which uvx en tu terminal para encontrar la ruta (por ejemplo, /Users/yourusername/.local/bin/uvx).

Usa esa ruta absoluta en el campo command:
"command": "/Users/yourusername/.local/bin/uvx"

Claude Code

Específico del proyecto (predeterminado) — se instala en la configuración del directorio actual:

claude mcp add cerngitlab-mcp -- uvx cerngitlab-mcp

Global — se instala para tu cuenta de usuario (funciona en todos los proyectos):

claude mcp add --scope user cerngitlab-mcp -- uvx cerngitlab-mcp

Para incluir autenticación, agrega -e CERNGITLAB_TOKEN=glpat-xxxxxxxxxxxx antes del --:

# Example: Global installation with token
claude mcp add --scope user -e CERNGITLAB_TOKEN=glpat-xxxxxxxxxxxx cerngitlab-mcp -- uvx cerngitlab-mcp

Configuración manual — también puedes editar manualmente tu configuración global en ~/.claude.json (en Linux/macOS) o %APPDATA%\Claude\claude.json (en Windows):

{
  "mcpServers": {
    "cerngitlab": {
      "command": "uvx",
      "args": ["cerngitlab-mcp"],
      "env": {
        "CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
      }
    }
  }
}

GitHub Copilot

Agrega a tu settings.json de VS Code:

{
  "mcp": {
    "servers": {
      "cerngitlab": {
        "command": "uvx",
        "args": ["cerngitlab-mcp"],
        "env": {
          "CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
        }
      }
    }
  }
}

O agrega un .vscode/mcp.json a tu proyecto:

{
  "servers": {
    "cerngitlab": {
      "command": "uvx",
      "args": ["cerngitlab-mcp"],
      "env": {
        "CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
      }
    }
  }
}

Gemini CLI

Agrega a tu ~/.gemini/settings.json:

{
  "mcpServers": {
    "cerngitlab": {
      "command": "uvx",
      "args": ["cerngitlab-mcp"],
      "env": {
        "CERNGITLAB_TOKEN": "glpat-xxxxxxxxxxxx"
      }
    }
  }
}

Uso directo

Modo Stdio (usuario único, predeterminado)

# Run with uvx (no install needed)
uvx cerngitlab-mcp

# Or if installed from PyPI
cerngitlab-mcp

# Explicit stdio mode
cerngitlab-mcp --mode stdio

# Or from source
uv run cerngitlab-mcp

# With authentication
CERNGITLAB_TOKEN=glpat-xxx uvx cerngitlab-mcp

Modo HTTP (multi-usuario)

# HTTP mode for multi-user deployment
cerngitlab-mcp --mode http --host 0.0.0.0 --port 8080

# Or use environment variables
CERNGITLAB_HTTP_MODE=true CERNGITLAB_HOST=0.0.0.0 CERNGITLAB_PORT=8080 cerngitlab-mcp

# Dedicated HTTP entry point
cerngitlab-mcp-http

Selección de modo

--mode stdio — Modo de usuario único usando stdin/stdout (predeterminado)
--mode http — Modo multi-usuario usando API HTTP
--mode auto — Auto-detección basada en variables de entorno

El servidor detecta automáticamente el modo HTTP si las variables de entorno CERNGITLAB_HTTP_MODE, CERNGITLAB_HOST o CERNGITLAB_PORT están establecidas.

Herramientas

Herramienta	Descripción	Autenticación requerida
`search_projects`	Buscar proyectos públicos de CERN GitLab (repositorios) por palabra clave, tema o lenguaje	No
`get_project_info`	Obtener metadatos detallados del proyecto (estrellas, descripción, lenguajes, estadísticas)	No
`list_branches`	Listar o buscar ramas del proyecto y sus metadatos de commits	No
`list_project_files`	Listar archivos y directorios en el repositorio de un proyecto	No
`get_file_content`	Obtener el contenido de un archivo específico (incluye detección binaria)	No
`get_project_readme`	Obtener el contenido del README de un proyecto	No
`search_code`	Buscar código dentro de un proyecto específico o globalmente	Sí*
`search_lhcb_stack`	Buscar código dentro de un stack de software LHCb (por ejemplo, 'sim11'), con resolución automática de referencia Git	Sí*
`search_issues`	Buscar issues en un proyecto	Sí
`get_wiki_pages`	Listar páginas wiki de un proyecto	Sí
`inspect_project`	Analizar estructura del proyecto, sistema de compilación, dependencias y CI/CD	No
`list_releases`	Listar releases de un proyecto	No
`get_release`	Obtener detalles de un release específico	No
`list_tags`	Listar etiquetas de un proyecto	No
`test_connectivity`	Probar conexión con la instancia de GitLab	No

Para documentación detallada de parámetros, consulta docs/dev.md.

Ejemplos de Prompts

Buscar repositorios

"Busca en CERN GitLab repositorios de Python relacionados con análisis ROOT y muéstrame los más destacados"

Entender un proyecto

"Obtén el README y la estructura de archivos del proyecto lhcb/DaVinci en CERN GitLab"

Explorar una rama

"Encuentra ramas que contengan 'release' en lhcb/DaVinci, luego busca en la rama seleccionada la configuración de Scheduler"

Encontrar ejemplos adecuados

"Busca repositorios en CERN GitLab que usen RooFit y muéstrame código de ejemplo de ajuste"

Ver código del stack de software LHCb

"Busca en el stack sim11 de LHCb las rutinas de inicialización en el proyecto Boole"

Analizar la estructura de un proyecto

"Inspecciona el proyecto lhcb/allen para entender su sistema de compilación, dependencias y configuración de pipeline CI"

Encontrar contexto de uso

"Busca issues relacionados con 'segmentation fault' en el proyecto atlas/athena para ver si otros han encontrado esto"

Rastrear releases

"Lista los releases recientes de lhcb/DaVinci y muéstrame las notas de release de la versión más reciente"

Encontrar configuraciones de frameworks

"Busca archivos de configuración del framework Gaudi en CERN GitLab y muéstrame ejemplos"

Desarrollo

Consulta docs/dev.md para la configuración de desarrollo, estructura del proyecto, pruebas e instrucciones de release.

Despliegue HTTP Multi-Usuario

El modo HTTP proporciona un servidor centralizado para múltiples usuarios. Usa CERN SSO + GitLab OAuth para la autenticación, los usuarios se autentican con su identidad CERN existente, y el sistema de permisos propio de GitLab aplica todos los controles de acceso.

Requisitos previos

Cliente CERN SSO — Registra un cliente en el Servicio de Autorización de CERN. Anota el ID de cliente.
Aplicación OAuth de GitLab — Crea una en https://gitlab.cern.ch/-/profile/applications.
- Establece la URI de redirección a https://gitlabmcp.cern.ch/oauth/callback (reemplaza con la URL real)
- Habilita los alcances read_api read_repository read_user
- Anota el ID y secreto de la aplicación.

Configuración

export CERNGITLAB_CERN_CLIENT_ID=your-cern-sso-client-id
export CERNGITLAB_GITLAB_OAUTH_CLIENT_ID=your-gitlab-oauth-app-id
export CERNGITLAB_GITLAB_OAUTH_CLIENT_SECRET=your-gitlab-oauth-secret
export CERNGITLAB_SERVER_BASE_URL=https://gitlabmcp.cern.ch
export CERNGITLAB_SESSION_STORAGE_PATH=/var/lib/cerngitlab/sessions  # optional

# Start the server
cerngitlab-mcp --mode http --host 0.0.0.0 --port 8000

Consulta examples/oauth_server.py en el repositorio para un script de referencia autocontenido.

Flujo de autenticación

El cliente envía una solicitud con el encabezado Authorization: Bearer <cern-sso-token>.
El servidor valida el token de CERN SSO mediante el endpoint JWKS de CERN.
Si el usuario no tiene una sesión OAuth de GitLab activa, el servidor devuelve HTTP 202 con un campo authorization_url.
El usuario visita esa URL, autoriza la aplicación OAuth de GitLab y es redirigido de vuelta a /oauth/callback.
Las solicitudes posteriores se atienden usando el token OAuth de GitLab almacenado. Las sesiones expiran después de 2 horas.

Endpoints de API

Método	Ruta	Autenticación	Descripción
`GET`	`/`	—	Información del servidor
`GET`	`/health`	—	Verificación de salud
`GET`	`/oauth/authorize`	CERN SSO	Iniciar o verificar el flujo de autorización OAuth
`GET`	`/oauth/callback`	—	Recibir el código OAuth de GitLab (redirección del navegador)
`GET`	`/tools`	CERN SSO	Listar herramientas MCP disponibles
`POST`	`/tools/{tool_name}`	CERN SSO	Ejecutar una herramienta específica
`DELETE`	`/session`	CERN SSO	Revocar la sesión OAuth del usuario actual
`GET`	`/admin/sessions`	—	Listar todas las sesiones activas (uso administrativo)

Ejemplo de uso

Suponiendo que el servidor se ejecuta en https://gitlabmcp.cern.ch y la variable de entorno CERN_SSO_TOKEN está establecida con un token válido de CERN SSO:

# Step 1 – check authorization status
curl -H "Authorization: Bearer $CERN_SSO_TOKEN" \
     https://gitlabmcp.cern.ch/oauth/authorize
# If 202, visit the returned authorization_url in a browser and authorize.

# Step 2 – list available tools (once authorized)
curl -H "Authorization: Bearer $CERN_SSO_TOKEN" \
     https://gitlabmcp.cern.ch/tools

# Step 3 – execute a tool
curl -X POST -H "Authorization: Bearer $CERN_SSO_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"arguments": {"query": "ROOT"}}' \
     https://gitlabmcp.cern.ch/tools/search_projects

# Revoke session
curl -X DELETE -H "Authorization: Bearer $CERN_SSO_TOKEN" \
     https://gitlabmcp.cern.ch/session

Herramienta CLI

También está disponible una interfaz de línea de comandos para uso directo sin el servidor MCP:

# Install or use with uvx
uvx cerngitlab-cli

# Test connectivity
cerngitlab-cli test-connection

# Search for projects
cerngitlab-cli search-projects --query "ROOT analysis" --language python

# Get project info
cerngitlab-cli get-project-info --project lhcb/DaVinci

# Search code
cerngitlab-cli search-code --search-term "RooFit" --per-page 10

# Inspect project structure
cerngitlab-cli inspect-project --project lhcb/allen

Todos los comandos emiten JSON a stdout para facilitar el encadenamiento y la composición. Consulta cerngitlab-cli --help para la lista completa de comandos.

Archivo de Habilidades

Un archivo de habilidades detallado (SKILL.md) está disponible con:

Documentación completa de las 15 herramientas
Especificaciones de entrada/salida
Ejemplos de uso
Requisitos de autenticación

Puede ser usado por LLMs o agentes para entender las herramientas disponibles y cómo usarlas.

Licencia

Este software se proporciona bajo la licencia AGPL-3.0.

cerngitlab-mcp

Documentación

Servidor MCP de CERN GitLab

Características

Instalación

Inicio rápido (recomendado)

Desde PyPI

Desde el código fuente

Configuración

Autenticación

Uso

Claude Desktop

Claude Code

GitHub Copilot

Gemini CLI

Uso directo

Modo Stdio (usuario único, predeterminado)

Modo HTTP (multi-usuario)

Selección de modo

Herramientas

Ejemplos de Prompts

Buscar repositorios

Entender un proyecto

Explorar una rama

Encontrar ejemplos adecuados

Ver código del stack de software LHCb

Analizar la estructura de un proyecto

Encontrar contexto de uso

Rastrear releases

Encontrar configuraciones de frameworks

Desarrollo

Despliegue HTTP Multi-Usuario

Requisitos previos

Configuración

Flujo de autenticación

Endpoints de API

Ejemplo de uso

Herramienta CLI

Archivo de Habilidades

Licencia