Продвинутый MCP-сервер GitLab

Продвинутый MCP-сервер GitLab — 44 инструмента для 18 типов сущностей с архитектурой CQRS, поддержкой OAuth 2.1 и несколькими режимами транспорта.

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

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@structured-world/gitlab-mcp"],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "https://gitlab.com"
      }
    }
  }
}

Требования: Node.js >= 24

Related MCP server: GitLab MCP Server

Основные возможности

• 44 инструмента для 18 типов сущностей — проекты, запросы на слияние (merge requests), конвейеры (pipelines), рабочие элементы, вики и многое другое

• Архитектура CQRS — browse_* для запросов, manage_* для команд

• Устойчивость соединения — ограниченное время запуска, автоматическое переподключение с экспоненциальной задержкой, режим отключения при недоступности GitLab

• Поддержка нескольких экземпляров — подключение к нескольким инстансам GitLab с индивидуальным OAuth и ограничением частоты запросов для каждого

• Несколько транспортов — stdio, SSE, StreamableHTTP

• OAuth 2.1 — аутентификация пользователя через Claude Custom Connector

• Режим «только чтение» — безопасная работа в производственных средах

• Автообнаружение — определение конфигурации GitLab из удаленных репозиториев git

• Тонкая настройка — включение/отключение групп инструментов, фильтрация действий, настройка описаний

• Поддержка Docker — ghcr.io/structured-world/gitlab-mcp:latest

Документация

Полная документация доступна на сайте gitlab-mcp.sw.foundation

Автоматически генерируемый справочник инструментов

Для получения полного справочника инструментов с параметрами:

# View locally
yarn list-tools --detail

# Generate documentation
yarn list-tools --export --toc > docs/tools/api-reference.md

См. Полный справочник API для получения автоматически сгенерированной документации по инструментам.

Docker

# HTTP mode
docker run -e PORT=3002 -e GITLAB_TOKEN=your_token -p 3333:3002 \
  ghcr.io/structured-world/gitlab-mcp:latest

# stdio mode
docker run -i --rm -e GITLAB_TOKEN=your_token \
  ghcr.io/structured-world/gitlab-mcp:latest

Устойчивость соединения

Сервер корректно обрабатывает проблемы с подключением к GitLab:

• Ограниченное время запуска — сервер запускается в течение GITLAB_INIT_TIMEOUT_MS (по умолчанию 5 с) независимо от доступности GitLab

• Режим отключения — когда GitLab недоступен (состояние disconnected/failed), доступен только инструмент manage_context с локальными действиями, такими как whoami, switch_profile и set_scope для диагностики. Во время активного переподключения (состояние connecting) полный список инструментов остается доступным, чтобы клиенты MCP не теряли каталог инструментов во время кратковременных сбоев. Клиенты MCP уведомляются об изменениях доступности инструментов через tools/list_changed

• Автоматическое переподключение — переподключение с экспоненциальной задержкой (5 с → 60 с) с джиттером ±10%

• Классификация ошибок — временные ошибки (сеть, 5xx, тайм-ауты) вызывают автоматическое переподключение. Ошибки аутентификации/конфигурации при запуске переводят сервер в состояние failed (без автоматического переподключения). Отзыв токена в середине сессии обнаруживается с помощью аутентифицированной проверки HEAD /api/v4/user, которая выполняется вместе с каждой периодической проверкой работоспособности (только в режиме статического токена; пропускается в режиме OAuth). Ошибка 401 или 403 при этой проверке немедленно переводит экземпляр в состояние failed.

• Мониторинг работоспособности экземпляра — каждый отслеживаемый URL экземпляра имеет свою машину состояний XState. Неотслеживаемые URL OAuth в настоящее время проходят как доступные.

Флаги функций

Участие в разработке

См. CONTRIBUTING.md для настройки среды разработки, тестирования и правил подачи PR.

Поддержка проекта

USDT (TRC-20): TFDsezHa1cBkoeZT5q2T49Wp66K8t2DmdA

Лицензия

Apache License 2.0 — подробности см. в LICENSE.

Основано на zereight/gitlab-mcp (MIT). См. LICENSE.MIT.