GitLab AI MCP Server

Un servidor de alto rendimiento y contenerizado de Model Context Protocol (MCP) que conecta asistentes de codificación con IA (Claude, Codex, Gemini, Kimi) a cualquier instancia de GitLab, ya sea autoalojada o en la nube.

Qué puedes hacer

Related MCP server: GitLab MCP Server

🚀 Inicio rápido

Requisitos previos

• Docker y Docker Compose v2

• Un token de acceso personal de GitLab con el alcance api

Usuarios de WSL2 (Windows): Instala Docker Desktop para Windows con el backend WSL2 habilitado — es la forma más sencilla. Todos los comandos siguientes se ejecutan dentro de tu terminal WSL2.

1. Clona y configura

git clone https://github.com/haziqasjad/gitlab-ai-mcp.git
cd gitlab-ai-mcp
cp .env.example .env

Edita .env:

GITLAB_URL=https://gitlab.example.com   # your GitLab instance URL
GITLAB_TOKEN=glpat-your-token           # your Personal Access Token

2. Elige tu configuración y comienza

Opción A — Solo el núcleo (recomendada para empezar: sin IA local, funciona en cualquier máquina):

docker compose up -d --build

Opción B — Con IA local en CPU (Ollama se ejecuta en CPU, descarga de modelo ~4 GB en el primer uso):

docker compose --profile ollama up -d --build

Opción C — Con IA local en GPU NVIDIA (inferencia más rápida: requiere configuración adicional abajo):

docker compose --profile ollama -f docker-compose.yml -f docker-compose.gpu.yml up -d --build

Las opciones B y C habilitan funciones adicionales de IA: clasificación de registros, escaneo de privacidad, resumen de discusiones. Si Ollama no está en ejecución, estas funciones devuelven un error claro — el resto de funciones funcionan con normalidad.

Configuración de la GPU NVIDIA (solo Opción C)

Omite esta sección si no tienes una GPU NVIDIA — la Opción B funciona bien en CPU.

🐧 Linux nativo

Paso 1 — Verifica que los controladores NVIDIA estén instalados:

nvidia-smi

Deberías ver tu GPU en la lista. Si no, instala primero los controladores para tu distribución: Descargas de controladores NVIDIA

Paso 2 — Instala NVIDIA Container Toolkit (Ubuntu/Debian):

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
  | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt update && sudo apt install -y nvidia-container-toolkit

Para otras distribuciones, consulta la guía oficial de instalación.

Paso 3 — Configura Docker y verifica:

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# Confirm Docker can see your GPU
docker run --rm --gpus all ubuntu nvidia-smi

Paso 4 — Inicia el stack:

docker compose --profile ollama -f docker-compose.yml -f docker-compose.gpu.yml up -d --build

🪟 WSL2 (Windows)

WSL2 usa los controladores NVIDIA instalados en Windows — no instales controladores de GPU dentro de WSL.

Paso 1 — Instala los controladores NVIDIA en Windows (si aún no están instalados):

Descarga e instala desde Descargas de controladores NVIDIA. Reinicia Windows después de instalar.

Paso 2 — Verifica que la GPU sea visible dentro de WSL2:

nvidia-smi

Si esto funciona, tu GPU está disponible en WSL2. Si no, asegúrate de tener WSL2 (no WSL1):

wsl --set-default-version 2

Paso 3 — Instala NVIDIA Container Toolkit dentro de WSL2:

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
  | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt update && sudo apt install -y nvidia-container-toolkit

Paso 4 — Configura Docker:

Si usas Docker Desktop para Windows (recomendado):

• Abre Docker Desktop → Configuración → Recursos → GPU → habilita tu GPU → Aplicar y reiniciar

Si usas Docker Engine directamente en WSL2:

sudo nvidia-ctk runtime configure --runtime=docker
sudo service docker restart   # WSL2 uses service, not systemctl

Paso 5 — Verifica que Docker pueda ver tu GPU:

docker run --rm --gpus all ubuntu nvidia-smi

Paso 6 — Inicia el stack:

docker compose --profile ollama -f docker-compose.yml -f docker-compose.gpu.yml up -d --build

3. Verifica que el servidor esté en ejecución

docker compose ps

Deberías ver gitlab-ai-mcp con el estado Up. Pruébalo directamente:

docker compose exec gitlab-ai-mcp python run_tests.py

4. Regístralo con tu CLI de IA

Primero, obtén la ruta de tu checkout:

pwd   # run this inside the Gitlab_AI_MCP directory

Usuarios de WSL2: Usa la ruta de Linux que muestra pwd (p. ej. /home/yourname/Gitlab_AI_MCP), no la ruta de Windows. Tu CLI de IA debe estar ejecutándose dentro de la misma terminal WSL2 para que esta ruta funcione.

Luego regístralo usando esa ruta:

Claude Code:

claude mcp add gitlab-ai-mcp -- /your/path/to/Gitlab_AI_MCP/scripts/run_codex_mcp.sh

Codex CLI:

codex mcp add gitlab-ai-mcp -- /your/path/to/Gitlab_AI_MCP/scripts/run_codex_mcp.sh

Gemini CLI:

gemini mcp add gitlab-ai-mcp -- /your/path/to/Gitlab_AI_MCP/scripts/run_codex_mcp.sh

Kimi Code CLI:

kimi mcp add gitlab-ai-mcp -- /your/path/to/Gitlab_AI_MCP/scripts/run_codex_mcp.sh

⚙️ Configuración

Todos los ajustes van en tu archivo .env:

🔧 Solución de problemas

El contenedor no arranca:

docker compose logs gitlab-ai-mcp

Errores de GITLAB_TOKEN o GITLAB_URL:

• Asegúrate de que tu archivo .env exista y no tenga espacios adicionales alrededor de =

• Confirma que tu token tenga el alcance api en GitLab → Configuración → Tokens de acceso

El modelo de Ollama no se descarga (Opciones B/C):

docker compose logs gitlab-ai-ollama-pull

GPU no detectada (Opción C):

• Ejecuta nvidia-smi — si falla, tus controladores no están instalados

• Ejecuta docker run --rm --gpus all ubuntu nvidia-smi — si falla, el Container Toolkit no está configurado

WSL2 — nvidia-smi no encontrado dentro de WSL:

• Asegúrate de estar en WSL2, no en WSL1: ejecuta wsl --list --verbose en PowerShell y revisa la columna VERSION

• Instala los controladores NVIDIA en Windows (no dentro de WSL) y reinicia

WSL2 — systemctl: comando no encontrado:

• WSL2 no usa systemd de forma predeterminada — usa sudo service docker restart en su lugar

• O habilita systemd en WSL2: añade [boot] systemd=true a /etc/wsl.conf y luego reinicia WSL (wsl --shutdown en PowerShell)

WSL2 — Falta la opción de GPU en Docker Desktop:

• Requiere Docker Desktop 4.17 o posterior y el backend WSL2 — actualiza Docker Desktop si la opción de GPU no está visible

WSL2 — docker compose no encontrado:

• Docker Desktop instala Compose automáticamente — abre Docker Desktop y asegúrate de que esté en ejecución antes de usar la terminal WSL2

📁 Estructura del proyecto

server.py                  — MCP server entrypoint
config.py                  — Settings (reads from .env)
gitlab/client.py           — Async HTTP/2 GitLab API client
services/
  gitlab_service.py        — Business logic and response formatting
  local_ai_service.py      — Ollama integration for local AI features
  review_digest.py         — MR discussion digest helpers
tools/                     — MCP tool definitions (one file per domain)
tests/                     — Unit tests
scripts/run_codex_mcp.sh   — Launcher used by all AI CLIs
docker-compose.yml         — Base stack
docker-compose.gpu.yml     — NVIDIA GPU override (use with --profile ollama)