GitLab AI MCP Server

A high-performance, containerized Model Context Protocol (MCP) server that connects AI coding assistants (Claude, Codex, Gemini, Kimi) to any GitLab instance — self-hosted or cloud.

Что вы можете делать

Related MCP server: GitLab MCP Server

🚀 Быстрый старт

Предварительные требования

• Docker и Docker Compose v2

• Личный токен доступа GitLab с областью api

WSL2 (пользователи Windows): Установите Docker Desktop for Windows с включённым бэкендом WSL2 — это самый простой способ. Все команды ниже выполняются в вашем терминале WSL2.

1. Клонирование и настройка

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

Отредактируйте .env:

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

2. Выбор варианта установки и запуск

Вариант A — только ядро (рекомендуется для начала — без локального ИИ, работает на любом компьютере):

docker compose up -d --build

Вариант B — с локальным ИИ на CPU (Ollama работает на CPU, при первом запуске загружается модель ~4 ГБ):

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

Вариант C — с локальным ИИ на NVIDIA GPU (самый быстрый инференс — требует дополнительной настройки ниже):

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

Варианты B и C включают дополнительные функции ИИ: сортировка логов, проверка конфиденциальности, обобщение обсуждений. Если Ollama не запущен, эти функции возвращают понятную ошибку — все остальные функции работают нормально.

Настройка NVIDIA GPU (только вариант C)

Пропустите этот раздел, если у вас нет NVIDIA GPU — вариант B отлично работает на CPU.

🐧 Нативный Linux

Шаг 1 — Проверьте, что драйверы NVIDIA установлены:

nvidia-smi

Вы должны увидеть свою GPU в списке. Если её нет, сначала установите драйверы для вашего дистрибутива: NVIDIA Driver Downloads

Шаг 2 — Установите 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

Для других дистрибутивов смотрите официальное руководство по установке.

Шаг 3 — Настройте Docker и проверьте:

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

Шаг 4 — Запустите стек:

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

🪟 WSL2 (Windows)

WSL2 использует драйверы NVIDIA, установленные в Windows — вам не нужно устанавливать драйверы GPU внутри WSL.

Шаг 1 — Установите драйверы NVIDIA в Windows (если они ещё не установлены):

Скачайте и установите с NVIDIA Driver Downloads. Перезагрузите Windows после установки.

Шаг 2 — Проверьте, что GPU видна внутри WSL2:

nvidia-smi

Если это работает, ваша GPU доступна в WSL2. Если нет, убедитесь, что у вас WSL2 (а не WSL1):

wsl --set-default-version 2

Шаг 3 — Установите NVIDIA Container Toolkit внутри 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

Шаг 4 — Настройте Docker:

Если вы используете Docker Desktop for Windows (рекомендуется):

• Откройте Docker Desktop → Settings → Resources → GPU → включите вашу GPU → Apply & Restart

Если вы используете Docker Engine напрямую в WSL2:

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

Шаг 5 — Проверьте, что Docker видит вашу GPU:

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

Шаг 6 — Запустите стек:

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

3. Проверка запуска сервера

docker compose ps

Вы должны увидеть gitlab-ai-mcp со статусом Up. Проверьте его напрямую:

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

4. Регистрация в вашем AI CLI

Сначала получите путь к копии репозитория:

pwd   # run this inside the Gitlab_AI_MCP directory

Пользователям WSL2: Используйте путь Linux, который показывает pwd (например, /home/yourname/Gitlab_AI_MCP), а не путь Windows. Ваш AI CLI должен быть запущен в том же терминале WSL2, чтобы этот путь работал.

Затем зарегистрируйте сервер, используя этот путь:

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

⚙️ Конфигурация

Все настройки указываются в вашем файле .env:

🔧 Устранение неполадок

Контейнер не запускается:

docker compose logs gitlab-ai-mcp

Ошибки GITLAB_TOKEN или GITLAB_URL:

• Убедитесь, что ваш файл .env существует и в нём нет лишних пробелов вокруг =

• Подтвердите, что ваш токен имеет область api в GitLab → Settings → Access Tokens

Модель Ollama не загружается (варианты B/C):

docker compose logs gitlab-ai-ollama-pull

GPU не обнаружена (вариант C):

• Выполните nvidia-smi — если это не сработает, драйверы не установлены

• Выполните docker run --rm --gpus all ubuntu nvidia-smi — если это не сработает, Container Toolkit не настроен

WSL2 — nvidia-smi не найден внутри WSL:

• Убедитесь, что вы используете WSL2, а не WSL1: выполните wsl --list --verbose в PowerShell и проверьте столбец VERSION

• Установите драйверы NVIDIA в Windows (не внутри WSL) и перезагрузитесь

WSL2 — systemctl: command not found:

• WSL2 по умолчанию не использует systemd — используйте sudo service docker restart

• Или включите systemd в WSL2: добавьте [boot] systemd=true в /etc/wsl.conf, затем перезапустите WSL (wsl --shutdown в PowerShell)

WSL2 — переключатель GPU в Docker Desktop отсутствует:

• Требуется Docker Desktop 4.17 или новее и бэкенд WSL2 — обновите Docker Desktop, если параметр GPU не отображается

WSL2 — docker compose не найдена:

• Docker Desktop устанавливает Compose автоматически — откройте Docker Desktop и убедитесь, что он запущен, перед использованием терминала WSL2

📁 Структура проекта

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)