MCP GitLab CrunchTools

Un servidor MCP (Model Context Protocol) seguro para proyectos, solicitudes de fusión, incidencias, pipelines y búsqueda de GitLab. Funciona con cualquier instancia de GitLab (gitlab.com, autoalojada o empresarial).

Resumen

Este servidor MCP está diseñado para ser:

• Seguro por defecto - Modelado de amenazas integral, validación de entradas y protección de tokens

• Sin servicios de terceros - Se ejecuta localmente mediante stdio, tu token de API nunca sale de tu máquina

• Multi-instancia - Funciona con gitlab.com, GitLab autoalojado o instancias empresariales mediante URL configurable

• Multiplataforma - Funciona en Linux, macOS y Windows

• Actualizado automáticamente - GitHub Actions supervisa CVEs y actualiza dependencias

• Contenerizado - Disponible en quay.io/crunchtools/mcp-gitlab construido sobre la imagen base Hummingbird Python

Related MCP server: gitlab-mcp-server

Convención de nombres

¿Por qué Hummingbird?

La imagen del contenedor está construida sobre la imagen base Hummingbird Python de Project Hummingbird, que proporciona:

• Exposición mínima a CVE - Construido con un conjunto mínimo de paquetes, lo que reduce drásticamente la superficie de ataque

• Actualizaciones periódicas - Los parches de seguridad se aplican con prontitud

• Optimizado para Python - Entorno de Python preconfigurado con el gestor de paquetes uv

• Listo para producción - Manejo adecuado de señales y usuario no root por defecto

Características

Gestión de proyectos (5 herramientas)

• list_projects - Lista proyectos con filtrado y búsqueda

• get_project - Obtiene detalles del proyecto por ID o ruta

• list_project_branches - Lista las ramas del repositorio

• get_project_branch - Obtiene una sola rama

• list_project_commits - Lista commits con filtrado por fecha/ruta

Gestión de grupos (3 herramientas)

• list_groups - Lista grupos con filtrado

• get_group - Obtiene detalles del grupo por ID o ruta

• list_group_projects - Lista proyectos en un grupo (con soporte para subgrupos)

Solicitudes de fusión (7 herramientas)

• list_merge_requests - Lista MRs por estado, etiquetas, hito

• get_merge_request - Obtiene detalles del MR

• create_merge_request - Crea un nuevo MR

• update_merge_request - Actualiza título, descripción, estado y asignados del MR

• list_mr_notes - Lista comentarios en un MR

• create_mr_note - Añade un comentario a un MR

• get_mr_changes - Obtiene el diff de un MR

Incidencias (6 herramientas)

• list_issues - Lista incidencias por estado, etiquetas, hito, asignado

• get_issue - Obtiene detalles de la incidencia

• create_issue - Crea una nueva incidencia

• update_issue - Actualiza título, descripción, estado y etiquetas de la incidencia

• list_issue_notes - Lista comentarios en una incidencia

• create_issue_note - Añade un comentario a una incidencia

Pipelines (4 herramientas)

• list_pipelines - Lista pipelines de CI/CD con filtrado por estado

• get_pipeline - Obtiene detalles del pipeline

• list_pipeline_jobs - Lista trabajos en un pipeline

• get_job_log - Obtiene la salida del registro del trabajo

Búsqueda (2 herramientas)

• search_global - Busca en todos los recursos de GitLab accesibles

• search_project - Busca dentro de un proyecto específico

Instalación

Con uvx (Recomendado)

uvx mcp-gitlab-crunchtools

Con pip

pip install mcp-gitlab-crunchtools

Con contenedor

podman run -e GITLAB_TOKEN=your_token \
    quay.io/crunchtools/mcp-gitlab

Configuración

Variables de entorno

Creación de un token de acceso personal de GitLab

1. Navega a Tokens de acceso

   • Ve a https://gitlab.com/-/user_settings/personal_access_tokens

   • O: Avatar > Preferencias > Tokens de acceso

2. Crea un token personalizado

   • Nombre: mcp-gitlab-crunchtools

   • Caducidad: Establece una fecha adecuada (se recomiendan 90 días)

   • Ámbitos: Selecciona los ámbitos según tus necesidades

3. Selección de ámbitos

   Ámbito	Nivel de acceso	Capacidades
   read_api	Solo lectura	Listar/ver proyectos, incidencias, MRs, pipelines
   api	Acceso completo	Todas las funciones, incluida la creación/actualización

4. Copia y guarda el token

   • Copia el token inmediatamente (empieza por glpat-)

   • Guárdalo de forma segura en un gestor de contraseñas

Añadir a Claude Code

claude mcp add mcp-gitlab-crunchtools \
    --env GITLAB_TOKEN=your_token_here \
    -- uvx mcp-gitlab-crunchtools

Para GitLab autoalojado:

claude mcp add mcp-gitlab-crunchtools \
    --env GITLAB_TOKEN=your_token_here \
    --env GITLAB_URL=https://gitlab.example.com \
    -- uvx mcp-gitlab-crunchtools

Para la versión de contenedor:

claude mcp add mcp-gitlab-crunchtools \
    --env GITLAB_TOKEN=your_token_here \
    -- podman run -i --rm -e GITLAB_TOKEN quay.io/crunchtools/mcp-gitlab

Ejemplos de uso

Lista tus proyectos

User: List my GitLab projects
Assistant: [calls list_projects with membership=true]

Ver solicitudes de fusión

User: Show open merge requests for my-org/backend
Assistant: [calls list_merge_requests with project_id="my-org/backend"]

Crear una incidencia

User: Create an issue in my-org/backend titled "Fix login timeout"
Assistant: [calls create_issue with title="Fix login timeout"]

Comprobar el estado del pipeline

User: Show failed pipelines for my-org/api
Assistant: [calls list_pipelines with status="failed"]

Buscar código

User: Search for "authentication" in my-org/backend
Assistant: [calls search_project with scope="blobs"]

Seguridad

Este servidor se diseñó con la seguridad como preocupación principal. Consulta SECURITY.md para:

• Modelo de amenazas y vectores de ataque

• Arquitectura de defensa en profundidad

• Buenas prácticas para el manejo de tokens

• Reglas de validación de entradas

• Registro de auditoría

Características clave de seguridad

1. Protección de tokens

   • Almacenado como SecretStr (nunca se registra accidentalmente)

   • Solo variable de entorno (nunca en archivos o argumentos)

   • Saneado de todos los mensajes de error

2. Validación de entradas

   • Modelos Pydantic para todas las entradas

   • Validación de caracteres mediante lista blanca para IDs de proyectos/grupos

   • Prevención de recorrido de rutas

3. Endurecimiento de la API

   • Aplicación de HTTPS (excepto localhost)

   • Validación de certificados TLS

   • Tiempos de espera de solicitud (30s)

   • Límites de tamaño de respuesta (10MB)

4. Escaneo automatizado de CVE

   • GitHub Actions escanea dependencias semanalmente

   • Escaneo de seguridad del contenedor con Trivy

   • Análisis CodeQL para Python

Desarrollo

Configuración

git clone https://github.com/crunchtools/mcp-gitlab.git
cd mcp-gitlab
uv sync

Ejecutar pruebas

uv run pytest

Lint y verificación de tipos

uv run ruff check src tests
uv run mypy src

Construir contenedor

podman build -t mcp-gitlab .

Licencia

AGPL-3.0-or-later

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, lee SECURITY.md antes de enviar cambios relacionados con la seguridad.

Enlaces

• Documentación de la API REST de GitLab

• Documentación de FastMCP

• Especificación de MCP

• crunchtools.com