gitlab-mcp-server

GitLab MCP Server

Сервер Model Context Protocol (MCP), який надає весь GitLab API у вигляді інструментів, ресурсів та промптів MCP для AI-асистентів. Один статичний бінарний файл — без жодних залежностей.

Безпека понад усе: проєкт безперервно моніториться на SonarCloud із застосуванням quality gates, покриття тестами та сканування безпеки. Підтримуються режим лише для читання, безпечний режим (попередній перегляд без виконання) і самостійно розгорнутий GitLab із перевіркою TLS.

Дзеркало репозиторію: GitHub є канонічним репозиторієм. Дзеркало коду та релізів лише для читання доступне на GitLab.com для зручності пошуку; будь ласка, відкривайте внески з кодом на GitHub.

Обсяг токенів

Виміряно за допомогою go run ./cmd/gen_readme/ на поточному базовому каталозі. Підсумки оцінюють стартовий контекст, видимий MCP-клієнту: видимі схеми інструментів плюс спільні ресурси та промпти, використовуючи ту саму евристику «байти/4 = токени», що й cmd/audit_tokens.

Конфігурація за замовчуванням: коли TOOL_SURFACE не задано або TOOL_SURFACE=dynamic, CAPABILITY_SURFACE=full, META_TOOLS не задано, META_PARAM_SCHEMA=opaque, а GITLAB_ENTERPRISE не задано або false, сервер використовує динамічну поверхню find/execute. Використовуйте TOOL_SURFACE=meta лише тоді, коли вам явно потрібні доменні мета-інструменти; використовуйте TOOL_SURFACE=individual лише тоді, коли ваш клієнт здатен обробити повний каталог інструментів.

Рядки використовують базовий каталог Community Edition (GITLAB_ENTERPRISE=false). META_PARAM_SCHEMA=opaque впливає лише на видимі схеми входу мета-інструментів; динамічний режим отримує точні схеми дій від gitlab_find_action, і кожна поверхня публікує gitlab://tools та gitlab://tools/{id} для перегляду дій та схем входу за потреби. Індивідуальний режим уже надає одну схему на інструмент.

Основні можливості

• 1027 інструментів MCP на self-managed Enterprise/Premium, або 1033 на GitLab.com Enterprise/Premium з експериментальною підтримкою Orbit Knowledge Graph — широке покриття GitLab REST API v4 + GraphQL у 176 пакетах під internal/tools: проєкти, гілки, теги, релізи, merge requests, задачі, конвеєри, завдання, групи, користувачі, вікі, середовища, розгортання, пакети, реєстр контейнерів, runner-и, feature flags, змінні CI/CD, атрибути безпеки, категорії безпеки, шаблони, налаштування адміністратора, токени доступу, ключі розгортання, Orbit та інше
• Динамічний набір інструментів за замовчуванням — надає лише gitlab_find_action та gitlab_execute_action, зберігаючи той самий канонічний каталог дій GitLab. Опціональні доменні мета-інструменти залишаються доступними з TOOL_SURFACE=meta: 33 базові, 49 на self-managed Enterprise/Premium, або 50 на GitLab.com Enterprise/Premium
• Оцінка використання інструментів AI-моделями — автоматизовані запуски лише за схемою та на основі Docker проти заповнених екземплярів GitLab CE й ліцензованих Enterprise вимірюють вибір інструмента/дії, формування параметрів, відновлення після помилок GitLab і безпеку деструктивних дій для Anthropic, Google, OpenAI та Qwen. Опубліковані підсумки наведено в блоці керованої оцінки нижче; див. Результати оцінки AI-моделей
• 11 дій семплінгу — рев'ю коду за допомогою LLM, аналіз задач, діагностика збоїв конвеєра, рев'ю безпеки, нотатки до релізів, звіти за віхами тощо через мета-інструмент gitlab_analyze (можливість MCP sampling)
• 4 інструменти елісітації — інтерактивні майстри створення (задача, MR, реліз, проєкт) з покроковими запитами до користувача
• 46 ресурсів MCP у режимі за замовчуванням dynamic/full — дані лише для читання: користувач, групи, учасники групи, проєкти групи, проєкти, задачі, конвеєри, учасники, мітки, віхи, гілки, MR, релізи, теги, коміти, blob-и файлів, сторінки вікі, нотатки MR, обговорення MR, шаблони окремих сутностей (задача, MR, гілка, тег, реліз, мітка, віха, коміт, сторінка вікі, розгортання, середовище, завдання, дошка, snippet, ключ розгортання, feature flag, мітка групи, віха групи), маніфест gitlab://tools із урахуванням поверхні, шаблон деталей gitlab://tools/{id}, корені робочого простору та 5 посібників з найкращих практик робочого процесу
• 37 промптів MCP — оптимізовані для AI: рев'ю коду, статус конвеєра, оцінка ризиків, нотатки до релізів, standup, навантаження, статистика користувача, керування командою, міжпроєктні дашборди, аналітика, віхи, якість Git-робочого процесу, аудит
• 6 можливостей MCP — logging, completions, roots, progress, sampling, elicitation
• 50 іконок інструментів — SVG-іконки у форматі base64 (Sizes: ["any"]) на всіх інструментах, ресурсах і промптах для візуальної ідентифікації в MCP-клієнтах
• Пагінація на всіх ендпоінтах списків із метаданими (загальна кількість елементів, сторінки, наступна/попередня)
• Транспорти: stdio (за замовчуванням для десктопних AI) та HTTP (Streamable HTTP для віддалених клієнтів)
• Кросплатформність: Windows, Linux і macOS, amd64 та arm64
• Самостійно розгорнутий GitLab із підтримкою самопідписаних TLS-сертифікатів

Приклади промптів

Після підключення просто спілкуйтеся зі своїм AI-асистентом природною мовою:

«Покажи мої проєкти GitLab» «Покажи відкриті merge requests у my-app» «Створи merge request з feature-login до main» «Переглянь merge request !15 — чи безпечно його зливати?» «Покажи відкриті задачі, призначені мені» «Який статус конвеєра для проєкту 42?» «Чому впав останній конвеєр?» «Згенеруй нотатки до релізу від v1.0 до v2.0»

Сервер бере на себе переклад із природної мови у виклики GitLab API. Вам не потрібно знати ID проєктів, ендпоінти API чи синтаксис JSON — AI-асистент з'ясовує це за вас. Більше сценаріїв див. у Прикладах використання.

Швидкий старт

1. Отримайте сервер

Встановіть сервер із джерел через інструментарій Go (потрібен Go 1.26+):

# Встановити бінарний файл сервера за допомогою go install (рекомендований спосіб для CLI)
go install github.com/h0rn3t/gitlab-mcp-server/v2/cmd/server@latest

# Бінарний файл буде встановлено в $(go env GOPATH)/bin під назвою `server`.
# За бажанням перейменуйте його, щоб назва відповідала іншим прикладам:
mv "$(go env GOPATH)/bin/server" "$(go env GOPATH)/bin/gitlab-mcp-server"

Щоб додати сервер як залежність Go-модуля (для використання у власному коді), скористайтеся go get:

go get github.com/h0rn3t/gitlab-mcp-server/v2@latest

2. Налаштуйте доступ до GitLab

Рекомендовано: запустіть вбудований майстер налаштування — він налаштовує підключення до GitLab і ваш MCP-клієнт за один крок:

./gitlab-mcp-server --setup

Порада: майстер підтримує режими Web UI, Terminal UI та звичайний CLI. У Windows двічі клацніть .exe, щоб майстер запустився автоматично.

Для ручного налаштування потрібен лише персональний токен доступу GitLab зі скоупом api:

GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

GITLAB_URL за замовчуванням дорівнює https://gitlab.com; додавайте його лише тоді, коли підключаєтеся до self-managed екземпляра GitLab.

GITLAB_URL=https://gitlab.example.com

3. Підключіть ваш MCP-клієнт

Більшість десктопних клієнтів використовують stdio: клієнт запускає один локальний процес MCP-сервера і спілкується з ним через stdin/stdout. Виберіть один із цих шаблонів запуску.

Нативний бінарний файл (stdio)

Конфігурація MCP у стилі VS Code та Cursor:

Додайте до .vscode/mcp.json у вашому робочому просторі:

{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Claude Desktop використовує ту саму команду сервера в розділі mcpServers:

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Шляхи для конкретних клієнтів, безпечні запити токенів, HTTP OAuth та додаткові IDE див. у Конфігурації IDE.

Бінарний файл як HTTP MCP-сервер

Використовуйте режим HTTP для спільних, віддалених або багатокористувацьких розгортань. Ці приклади прив'язуються лише до loopback хоста.

# Фіксований екземпляр GitLab для всіх клієнтів
gitlab-mcp-server \
  --http \
  --http-addr=127.0.0.1:8080 \
  --gitlab-url=https://gitlab.com

# Багатоекземплярний режим: клієнти надсилають GITLAB-URL у кожному запиті
gitlab-mcp-server \
  --http \
  --http-addr=127.0.0.1:8080

HTTP-клієнти автентифікують кожен запит за допомогою PRIVATE-TOKEN або Authorization: Bearer:

{
  "servers": {
    "gitlab": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "PRIVATE-TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

У багатоекземплярному режимі клієнти також мають надсилати GITLAB-URL. Деталі про OAuth, зворотний проксі, обмеження частоти та пул серверів див. у Режимі HTTP-сервера.

4. Перевірте

Відкрийте ваш AI-клієнт і спробуйте:

«Покажи мої проєкти GitLab»

Детальні інструкції з налаштування див. у Посібнику з початку роботи.

Режими інструментів

Три режими реєстрації, керовані через TOOL_SURFACE:

Для динамічних експериментів, де ресурси та промпти домінують у початковому контексті, встановіть CAPABILITY_SURFACE=minimal (stdio) або --capability-surface=minimal (HTTP). Minimal залишає gitlab://workspace/roots плюс маніфест gitlab://tools із урахуванням поверхні, тож динамічні, мета- та індивідуальні розгортання все одно можуть читати прийняті форми викликів. Значення за замовчуванням залишається full.

Динамічний режим тепер є типовою низькотокенною поверхнею find/execute; див. Динамічний набір інструментів для моделі ранжування з урахуванням полів, нечіткого резервного варіанту, форм відповідей, діаграм робочих процесів і вказівок з міграції. Встановіть TOOL_SURFACE=meta, щоб використовувати консолідований каталог доменних мета-інструментів.

Детальний каталог мета-інструментів тепер знаходиться в Довіднику мета-інструментів, включно з кількістю дій, маркерами Enterprise/Premium та прикладами.

Сумісність

Протестовано з: VS Code + GitHub Copilot, Claude Desktop, Claude Code, Cursor, Windsurf, JetBrains IDE, Zed, Kiro, Cline, Roo Code.

Повну Матрицю сумісності з детальною підтримкою клієнтів див. за посиланням.

Оцінка використання інструментів AI-моделями

Проєкт містить автоматизований оцінювач якості MCP, орієнтованої на моделі. Він може виконувати перевірки лише за схемою проти каталогу інструментів або виконувати валідовані виклики інструментів моделями через MCP проти Docker GitLab CE чи ліцензованих екземплярів Enterprise, заповнених фікстурами. Оцінювач вимірює, чи кожна модель обирає правильний мета-інструмент і дію, чи надсилає валідні параметри, чи відновлюється після усувних помилок GitLab і чи поважає запобіжники деструктивних дій.

Поточний опублікований результат: Docker CE-on-Enterprise meta 20260527.

Опублікований набір оцінки моделей охоплює 560 спроб завдань і 1096 очікуваних операцій MCP. У вибраних звітах моделі видали 1109 викликів інструментів за 1145 запитів моделей із 100.0% сукупним фінальним успіхом. Детальну поточну матрицю див. у Результатах оцінки AI-моделей.

Поточний опублікований результат: Docker CE-on-Enterprise dynamic 20260525.

Опублікований набір оцінки моделей охоплює 560 спроб завдань і 1096 очікуваних операцій MCP. У вибраних звітах моделі видали 1136 викликів інструментів за 1136 запитів моделей із 100.0% сукупним фінальним успіхом. Детальну поточну матрицю див. у Результатах оцінки AI-моделей.

Поточний опублікований результат: Docker Enterprise meta 20260527.

Опублікований набір оцінки моделей охоплює 92 спроби завдань і 336 очікуваних операцій MCP. У вибраних звітах моделі видали 345 викликів інструментів за 350 запитів моделей із 100.0% сукупним фінальним успіхом. Детальну поточну матрицю див. у Результатах оцінки AI-моделей.

Поточний опублікований результат: Docker Enterprise dynamic 20260525.

Опублікований набір оцінки моделей охоплює 92 спроби завдань і 336 очікуваних операцій MCP. У вибраних звітах моделі видали 338 викликів інструментів за 338 запитів моделей із 100.0% сукупним фінальним успіхом. Детальну поточну матрицю див. у Результатах оцінки AI-моделей.

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

Повна документація доступна за адресою h0rn3t.github.io/gitlab-mcp-server. Використовуйте цю карту, коли вам потрібен авторитетний довідник для конкретної області:

Технологічний стек

Збірка з джерел

git clone https://github.com/h0rn3t/gitlab-mcp-server.git
cd gitlab-mcp-server
make build

Інструкції з кроскомпіляції та контрибуцій див. у Посібнику з розробки.

Поширені запитання

Контрибуції

Див. CONTRIBUTING.md для вказівок з розробки, іменування гілок, угод щодо комітів і процесу pull request.

Безпека

Див. SECURITY.md для політики безпеки та повідомлення про вразливості.

Кодекс поведінки

Див. CODE_OF_CONDUCT.md. Цей проєкт дотримується Contributor Covenant v2.1.

Непотрібна статистика

Числа, яких ніхто не просив, але ось вони.

File counts

Functions

Ratios worth noting

Code patterns

Project

Hall of fame

Because why not