GitLab MCP

GitLab MCP — это не зависящий от конкретной обвязки сервер Model Context Protocol, а также общие Agent Skills для работы с репозиториями GitLab. Codex, Claude Code, Cline и Pi — это поддерживаемые дистрибутивы одного и того же канонического ядра MCP, а не отдельные реализации GitLab. ChatGPT может использовать то же ядро через удалённое развёртывание Streamable HTTP.

Проект предоставляет:

• автономный сервер GitLab MCP с типизированными инструментами;

• общий навык $gitlab;

• $gl-address-comments для неразрешённых обсуждений в merge-request;

• $gl-fix-ci для диагностики пайплайнов и заданий;

• $gl-publish для доставки веток, коммитов, push и черновиков MR;

• нативные для GitLab рабочие процессы для раннеров, CI lint, управления, тегов, релизов и расписаний пайплайнов, а также безопасное управление переменными CI/CD проектов и групп;

• тонкие дистрибутивы для Codex, Claude Code, Cline и Pi, которые используют то же каноническое ядро и Agent Skills; и

• транспорт Streamable HTTP без сохранения состояния и метаданные защищённых ресурсов OAuth для развёртывания ChatGPT.

Начните здесь

Индекс документации содержит ссылки на полный набор документации для пользователей, операторов, разработчиков, по безопасности, совместимости и релизам.

Related MCP server: GitLab MCP Server

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

Для локальной установки из исходников используйте Node.js 22 или новее, затем соберите и проверьте каноническое ядро MCP:

npm.cmd ci
npm.cmd test
npm.cmd run build

Выберите адаптер, соответствующий вашей обвязке. Все четыре поддерживаемых адаптера используют один и тот же собранный MCP-бандл и канонические Agent Skills.

Для Codex добавьте этот репозиторий в доверенный локальный маркетплейс, установите плагин gitlab и перезапустите или обновите Codex. Установленный корневой манифест Codex .mcp.json, предзагрузка и имя артефакта остаются поддерживаемыми поверхностями совместимости. Настройте экземпляр GitLab и токен в окружении, которое запускает Codex:

$env:GITLAB_URL = "https://gitlab.example.com"
$env:GITLAB_TOKEN = "<token>"

Начните новый разговор и попросите Codex подтвердить подключение, например:

Use GitLab to tell me which account and instance are connected.

Пользователи Claude Code могут загрузить материализованный дистрибутив нативного плагина, который включает тот же MCP-сервер и канонические Agent Skills. См. руководство по адаптеру Claude Code для проверки пакета, загрузки через --plugin-dir и совместимой с маркетплейсом структуры.

Пользователи Cline могут использовать тот же канонический MCP-бандл через stdio и устанавливать канонические Agent Skills без отдельной реализации GitLab. См. руководство по адаптеру Cline для настройки IDE и CLI.

Пользователи Pi могут установить выделенный пакет Pi, который регистрирует канонический набор инструментов MCP через тонкий мост stdio и предоставляет те же Agent Skills. См. руководство по адаптеру Pi для установки пакета, обработки зависимостей времени выполнения и ограничений моста.

См. руководство пользователя для получения рекомендаций по токенам с минимальными привилегиями, типовым рабочим процессам GitLab и развёртыванию HTTP для ChatGPT.

Требования

• Node.js 22 или новее

• экземпляр GitLab.com, GitLab Dedicated или self-managed GitLab

• для локального использования через stdio — токен GitLab с минимальными областями, необходимыми для операций, которые вы собираетесь выполнять

Сборка и проверка

npm.cmd install
npm.cmd test
npm.cmd run adapters:check
npm.cmd run check:bundle
npm.cmd run build
npm.cmd run validate:codex
npm.cmd run validate:claude
npm.cmd run validate:cline
npm.cmd run validate:pi
npm.cmd run check:versions
npm.cmd run check:gitlab-oauth -- https://gitlab.example.com

Путь к каноническому MCP-бандлу определяется в distribution.json; текущая конфигурация собирает server/dist/gitlab-mcp.cjs. Сам MCP-бандл генерируется и игнорируется в системе контроля версий, а затем включается в артефакты релиза. Пакеты обвязок могут по-прежнему объявлять зависимость времени выполнения на стороне обвязки; например, пакет Pi использует MCP SDK для моста Pi к этому встроенному серверу.

distribution.json является авторитетным источником общих метаданных дистрибутива, включая нейтральный идентификатор дистрибутива gitlab, базовую версию, описание, лицензию, канонический MCP-бандл и путь к Skills. После его изменения выполните npm run adapters:generate и проверьте сгенерированные метаданные для Codex/Claude Code/Cline/Pi. npm run adapters:check отклоняет расхождение метаданных и отсутствующий, не являющийся каталогом или выходящий за пределы репозитория путь к каноническим Skills.

npm run check:bundle выполняет чистую сборку в памяти и завершается ошибкой, если канонический бандл содержит ссылки на реализации, специфичные для обвязки. npm run check:versions проверяет, что сгенерированные метаданные пакетов и релизов Codex остаются согласованными с distribution.json. Манифест плагина Codex может добавлять метаданные сборки Codex после + без изменения базовой версии дистрибутива. SERVER_VERSION управляется независимо нейтральным ядром MCP и увеличивается только при изменении самого ядра времени выполнения.

Нейтральное ядро и граница адаптера задокументированы в ADR-001. Сфокусированный аудит GEN-08 и решения по идентичности записаны в docs/GENERALISATION_AUDIT.md.

Непрерывная интеграция

Пайплайны GitLab для merge-request, ветки по умолчанию и тегов выполняют проверки синтаксиса, тесты, покрытие, dependency-cruiser, форматирование/линтинг, аудит производственных зависимостей, чистую сборку бандла и встроенные smoke-тесты stdio/HTTP. Также включены шаблоны GitLab SAST и обнаружения секретов. Codex, Claude Code, Cline и Pi имеют отдельную проверку адаптеров после канонической сборки; эти задания проверяют упаковку обвязки и запуск MCP без повторения основной матрицы Node/безопасности.

Пайплайны тегов дополнительно публикуют детерминированный архив Codex с его CycloneDX SBOM и SHA256SUMS, а также воспроизводимые архивы MCP + Skills для Claude Code, Cline и Pi с соответствующими файлами .sha256 в качестве артефактов заданий GitLab. Финальный шлюз набора релизов требует ровно четыре поддерживаемые обвязки и сравнивает их канонический MCP-бандл и дайджесты Skills. Релизы не считаются завершёнными, пока артефакты не проверены в соответствии с docs/PUBLICATION_CHECKLIST.md.

Зафиксированный инвентарь docs/gitlab-tool-contracts.json вызывает каждый зарегистрированный инструмент с гранично допустимыми входными данными и фиксирует его классификацию безопасности, HTTP-метод, закодированный маршрут, сопоставление запроса/тела и ограниченный режим ответа. Покрытие охватывает все производственные исходные модули и завершается ошибкой при покрытии строк ниже 90%, функций ниже 80% или ветвей ниже 75%; добавление инструмента без записи в инвентарь приводит к сбою теста.

Задания синтаксиса и тестов выполняются как на node:22-alpine, так и на node:24-alpine; задание покрытия с пороговым ограничением выполняется на Node 22. Основные задания требуют раннер Linux без тегов, который может запускать эти образы и получать доступ к реестру npm. Шаблоны безопасности загружают свои образы анализаторов из реестра GitLab. Привилегированный режим не требуется для основных заданий Node.js. Настройте хотя бы один раннер проекта, группы или экземпляра, который принимает задания без тегов и позволяет заданиям выполняться не менее 10 минут, прежде чем требовать успешных пайплайнов для слияния.

Локальная аутентификация Codex

Установите URL экземпляра и токен в окружении, которое запускает Codex:

$env:GITLAB_URL = "https://gitlab.example.com"
$env:GITLAB_TOKEN = "<token>"

GITLAB_URL по умолчанию должен использовать HTTPS и отклоняет встроенные учётные данные, запросы и фрагменты. Для явно локального/частного экземпляра GitLab для разработки, который не может использовать TLS, установите GITLAB_ALLOW_INSECURE_HTTP=true. Переопределение отклоняется в производственной среде и для публичных имен хостов; оно принимает loopback, IP-адреса частных сетей, односегментные имена хостов и частные суффиксы разработки .localhost, .local, .internal и .home.arpa.

GITLAB_URL по умолчанию равен https://gitlab.com. Файл .mcp.json Codex запускает встроенный сервер через stdio и загружает тонкий адаптер дистрибутива Codex перед нейтральным ядром. Токены считываются во время выполнения и никогда не хранятся в дистрибутиве.

Используйте самые узкие области токена, которые покрывают задачу. Работа только для чтения может использовать токен, ориентированный на чтение; изменения репозитория, задач, merge-request или CI требуют соответствующих разрешений API GitLab.

Обнаружение возможностей

Вызовите get_gitlab_capabilities перед диагностикой того, является ли операция GitLab неподдерживаемой, нелицензированной, отключённой или просто недоступной для текущего учётного данных. Он использует только запросы на чтение к /user, /version, /metadata, /personal_access_tokens/self и (когда учётные данные не являются персональным токеном доступа) /oauth/token/info. OAuth-диагностика сообщает области и оставшееся время жизни, но никогда не раскрывает токен или идентификатор приложения OAuth. GitLab может скрывать или опускать эти конечные точки, особенно на старых self-managed версиях или для не-администраторов, поэтому неоднозначные результаты сообщаются как unknown, а не угадываются.

Каждая возможность — одна из available, unavailable, permission_required, license_required, not_configured или unknown, с краткой причиной и подтверждающими доказательствами, где это полезно. Передайте detailed: true для нормализованных результатов по каждому зонду или refresh: true, чтобы обойти кэш.

Результаты кэшируются на 60 секунд для каждого нормализованного URL экземпляра и аутентифицированной идентичности учётных данных. Ключ кэша содержит односторонний дайджест SHA-256, никогда не сырой токен носителя. Записи истекают через 60 секунд, обходятся с помощью refresh и естественно разделяют экземпляры или изменённые учётные данные. Истёкшие записи удаляются при возможности, а предел LRU на 256 записей обеспечивает жёсткую границу памяти. Кэш находится только в памяти и очищается при перезапуске процесса MCP-сервера.

HTTP-сервер

Для локальной разработки:

$env:MCP_PUBLIC_URL = "https://mcp.example.com/mcp"
$env:GITLAB_URL = "https://gitlab.example.com"
npm.cmd run start:http

HTTP-режим требует токен носителя для каждого запроса /mcp. Серверный токен по умолчанию отключён. ALLOW_SERVER_TOKEN_HTTP=true существует только для контролируемого частного тестирования и не должен использоваться для общего развёртывания.

Установите MCP_READ_ONLY=true для развёртывания только для просмотра. В этом режиме сервер регистрирует только инструменты, помеченные как доступные только для чтения, и рекламирует область OAuth read_api GitLab. Режим по умолчанию с поддержкой записи предоставляет полный набор инструментов и требует api. Сервер проверяет каждую аннотацию инструмента во время регистрации, поэтому неклассифицированный или изменяющий инструмент не может незаметно попасть в поверхность только для чтения.

При привязке к IPv4-шаблону 0.0.0.0 или IPv6-шаблону :: задайте MCP_ALLOWED_HOSTS в виде разделённого запятыми списка разрешённых публичных имён хостов. Разместите сервис за HTTPS и задайте MCP_PUBLIC_URL в виде его канонического публичного URL-адреса /mcp. Производственный режим требует MCP_PUBLIC_URL, отклоняет встроенные учётные данные, параметры запроса, фрагменты и пути, отличные от /mcp, а также требует HTTPS. MCP_ALLOW_INSECURE_PUBLIC_URL=true доступен только для явной локальной разработки на loopback-слушателе и отклоняется в производственном режиме или на публичном хосте. ALLOW_SERVER_TOKEN_HTTP=true аналогично ограничен loopback-частным тестированием и не должен использоваться для общего развёртывания.

Используйте доступный только для чтения инструмент get_runtime_info после установки или развёртывания, чтобы подтвердить версии ядра/дистрибутива, режим развёртывания, фильтрацию только для чтения и детерминированный SHA-256-отпечаток зарегистрированного реестра инструментов.

Тела HTTP MCP-запросов по умолчанию ограничены 8 МиБ. Это обеспечивает поддержку ограниченных многофайловых коммитов и других допустимых крупных полезных нагрузок инструментов, предотвращая при этом неограниченную буферизацию запросов. Задайте MCP_MAX_REQUEST_BYTES целым числом от 65 536 до 26 214 400 байт, чтобы использовать другой предел развёртывания. Любой обратный прокси-сервер перед сервером должен допускать как минимум тот же размер запроса.

Долгоживущие HTTP-развёртывания также ограничивают состояние аутентификации и запросов:

• MCP_TOKEN_CACHE_MAX_ENTRIES ограничивает проверенные bearer-идентичности, по умолчанию 256, с TTL 60 секунд и LRU-вытеснением;

• MCP_AUTH_FAILURE_LIMIT ограничивает отклонённые токены на каждый напрямую подключённый адрес в пределах MCP_AUTH_FAILURE_WINDOW_MS, по умолчанию 20 сбоев за 60 секунд;

• MCP_AUTH_FAILURE_MAX_ENTRIES ограничивает состояние отслеживания сбоев, по умолчанию 1 024;

• MCP_MAX_CONCURRENT_REQUESTS ограничивает активные MCP-запросы, по умолчанию 32; и

• MCP_MAX_CONCURRENT_REQUESTS_PER_IDENTITY ограничивает запросы для одного проверенного пользователя GitLab, по умолчанию 4.

Настройте дополнительные ограничения скорости и соединений на TLS-обратном прокси. Приложение намеренно использует прямой адрес однорангового узла, а не доверяет forwarded-заголовкам по умолчанию, поэтому ограничения по IP-адресу клиента на уровне прокси должны применяться до того, как трафик достигнет этого сервиса.

Неаутентифицированная конечная точка /health — это проверка активности процесса без учёта топологии. /ready — это отдельная проверка готовности, которая возвращает 503, когда её проверка зависимостей недоступна. Каждый ответ включает сгенерированный X-Request-Id; внутренние MCP-сбои регистрируют только этот идентификатор и тип ошибки. Встраивающие системы могут предоставить наблюдатель завершения запроса для метрик, не получая bearer-токены или полезные нагрузки запросов.

После развёртывания проверьте метаданные публичного ресурса и обе семантики здоровья:

npm.cmd run check:mcp-deployment -- https://mcp.example.com/mcp

Модель безопасности

• Инструменты объявляют аннотации только для чтения, записи и деструктивные аннотации.

• create_commit поддерживает только недеструктивные действия с файлами; удаление и принудительные обновления коммитов требуют отдельно аннотированного инструмента create_destructive_commit с полями безопасности параллелизма.

• Тела ответов GitLab, включая журналы заданий, артефакты и ошибки API, передаются потоково в строгих байтовых пределах и остаются под действием таймаутов запросов;

• Ошибки API нормализуются без отражения учётных данных;

• Обнаружение возможностей скрывает доказательства ошибок и никогда не читает частные CI-переменные или конечные точки мутаций;

• HTTP bearer-токены проверяются на соответствие настроенному экземпляру GitLab и кэшируются по одностороннему хешу токена в ограниченном TTL/LRU-кэше;

• Отклонённые учётные данные и параллельные запросы ограничиваются без регистрации токенов или частных сведений об идентичности;

• HTTP-режим запрашивает у неаутентифицированных запросов метаданные защищённого ресурса;

• HTTP-инструменты объявляют схемы безопасности OAuth или частного серверного токена для каждого инструмента, а также видимые модели вызовы повторной авторизации; и

• Навыки требуют явного намерения для слияния, одобрения, удаления, разрешения обсуждений и изменений состояния CI.

Лицензия

MIT