Zereight Gitlab — MCP-сервер

Сервер MCP для GitLab

📖 Документация → руководство по настройке, переменные окружения, полный справочник инструментов доступны на размещенном сайте документации.

@zereight/mcp-gitlab

Полный сервер MCP для GitLab для клиента AI. Он позволяет управлять проектами, Merge Request, задачами (issues), пайплайнами, вики, релизами и вехами через stdio, SSE и Streamable HTTP.

Поддерживает PAT, OAuth, режим только для чтения, динамический API URL и удаленную аутентификацию, и доступен для использования в VS Code, Claude, Cursor, Copilot и других MCP-клиентах.

Зачем использовать этот GitLab MCP?

Широкая поддержка GitLab: проекты, навигация по репозиторию, Merge Request, задачи, пайплайны, вики, релизы, ярлыки, вехи и т. д.
Гибкая аутентификация: Personal Access Token, локальный OAuth2-браузерный поток, MCP OAuth-прокси, удаленная аутентификация по запросу.
Различные способы передачи: локальный stdio, SSE для устаревших клиентов, Streamable HTTP для современных удалённых развёртываний.
Дружелюбная настройка под клиентов: примеры для Claude Code, Codex, Antigravity, OpenCode, Copilot, Cline, Roo Code, Cursor, Kilo Code, Amp Code.
Поддержка самохостинга: настраиваемые GitLab-инстансы, настройки прокси, динамический маршрутизатор API URL.

Быстрый старт: ниже выберите один из вариантов настройки через Personal Access Token или OAuth2, затем установите @zereight/mcp-gitlab и выберите zereight-mcp-gitlab в настройках MCP-клиента.

Руководство по настройке клиента

Использование

Обзор настроек

Способы аутентификации

Этот сервер поддерживает четыре способа аутентификации.

Локальное/десктопное использование (самый распространённый):

Personal Access Token (GITLAB_PERSONAL_ACCESS_TOKEN) — наименее сложная настройка
OAuth2 — локальный браузер (GITLAB_USE_OAUTH) — рекомендуется для повышения безопасности

Сервер/удалённое развёртывание:

OAuth2 — MCP прокси (GITLAB_MCP_OAUTH) — для удалённых MCP-клиентов типа Claude.ai
Удаленная аутентификация (REMOTE_AUTHORIZATION) — для мульти-пользовательного развёртывания, где у каждого пользователя свой токен

Быстрая настройка

Claude Code: Настройка Claude Code
VS Code: Настройка VS Code
GitHub Copilot: Настройка GitHub Copilot
Codex: Настройка Codex
Cursor: Настройка Cursor
JSON‑клиенты: JSON-based MCP клиенты
OAuth2 (описание потока в браузере): OAuth2 настройка

Наиболее простую локальную настройку начните с Personal Access Token. Для браузерной локальной аутентификации используйте OAuth2. Для удалённых или мульти-пользовательных развёртываний смотрите разделы MCP OAuth и удалённой аутентификации ниже.

Установите сервер один раз.

brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp
brew install zereight/gitlab-mcp/zereight-mcp-gitlab

Также доступна установка через npm:

npm install -g @zereight/mcp-gitlab

Пример предполагает использование псевдонима zereight-mcp-gitlab, который менее подвержен конфликтам, чем стандартное имя mcp-gitlab. Если MCP-клиент не находится в PATH, используйте абсолютный путь, возвращаемый which zereight-mcp-gitlab.

Чтобы не использовать глобальную установку, зафиксируйте версию, например: npx -y @zereight/mcp-gitlab@2.1.45. Если нужна всегда самая новая версия, используйте npx -y @zereight/mcp-gitlab@latest. При выходе новой версии сервер сообщит об этом в stderr при запуске (можно отключить через GITLAB_DISABLE_VERSION_CHECK=true).

Использование CLI-аргументов (для клиентов с проблемами обработки переменных окружения)

Некоторые MCP-клиенты (например, GitHub Copilot CLI) могут некорректно обрабатывать переменные окружения. В таком случае используйте CLI-аргументы.

{
  "mcpServers": {
    "gitlab": {
      "command": "zereight-mcp-gitlab",
      "args": ["--token=YOUR_GITLAB_TOKEN", "--api-url=https://gitlab.com/api/v4"],
      "tools": ["*"]
    }
  }
}

Доступные CLI-аргументы:

--token – Personal Access Token GitLab (GITLAB_PERSONAL_ACCESS_TOKEN замещает)
--api-url – URL GitLab API (GITLAB_API_URL замещает)
--read-only=true – включить режим только для чтения (GITLAB_READ_ONLY_MODE замещает, устарело — рекомендуется --permission-mode=readonly)
--permission-mode – уровень прав: readonly, modify (запрет на удаление через инструменты), full (GITLAB_PERMISSION_MODE замещает, значение по умолчанию full)
--use-wiki=true – включить Wiki API (USE_GITLAB_WIKI замещает, устарело — рекомендуется GITLAB_TOOLSETS=wiki)
--use-milestone=true – включить Milestone API (USE_MILESTONE замещает, устарело — рекомендуется GITLAB_TOOLSETS=milestones)
--use-pipeline=true – включить Pipeline API (USE_PIPELINE замещает, устарело — рекомендуется GITLAB_TOOLSETS=pipelines)
--disable-version-check=true – отключить уведомления о новых версиях при старте (GITLAB_DISABLE_VERSION_CHECK замещает)

CLI-аргументы имеют приоритет над переменными окружения.

Тонкая настройка фильтра инструментов: можно установить GITLAB_PERMISSION_MODE=modify, чтобы разрешить создание/изменение, но ограничить удаление инструментов; или GITLAB_PERMISSION_MODE=readonly для полностью режима только для чтения. Можно активировать группы инструментов через GITLAB_TOOLSETS=<group,…> и разрешать только отдельные инструменты через GITLAB_TOOLS=<tool,…> (например, разрешить только read-инструменты и выбрать несколько write-инструментов). Можно также задать паттерн блокировки через GITLAB_DENIED_TOOLS_REGEX. Устаревшие флаги USE_GITLAB_WIKI / USE_MILESTONE / USE_PIPELINE сохраняются для обратной совместимости. Обратитесь к Tools Reference и Environment Variables для подробностей.

SSE

docker run -i --rm \
  -e HOST=0.0.0.0 \
  -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_PERMISSION_MODE=readonly \
  -e GITLAB_TOOLSETS=wiki,milestones,pipelines \
  -e SSE=true \
  -e SSE_AUTH_TOKEN=your_mcp_sse_token \
  -p 3333:3002 \
  zereight050/gitlab-mcp

{
  "mcpServers": {
    "gitlab": {
      "type": "sse",
      "url": "http://localhost:3333/sse",
      "headers": {
        "Authorization": "Bearer your_mcp_sse_token"
      }
    }
  }
}

Streamable HTTP

docker run -i --rm \
  -e HOST=0.0.0.0 \
  -e REMOTE_AUTHORIZATION=true \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_PERMISSION_MODE=readonly \
  -e GITLAB_TOOLSETS=wiki,milestones,pipelines \
  -e STREAMABLE_HTTP=true \
  -p 3333:3002 \
  zereight050/gitlab-mcp

{
  "mcpServers": {
    "gitlab": {
      "type": "streamable-http",
      "url": "http://localhost:3333/mcp",
      "headers": {
        "Authorization": "Bearer glpat-..."
      }
    }
  }
}

MCP OAuth прокси использование (`GITLAB_MCP_OAUTH`)

Только для серверов/удалённых развёртываний. Этот режим требует развертывания MCP сервера на общедоступном HTTPS URL. Локальное/рабочее использование — GITLAB_USE_OAUTH.

Сервер поддерживает OAuth 2.0 как полнофункционный OAuth- 인증-сервер для удалённых MCP-клиентов (например Claude.ai). Не требуется ручное управление Personal Access Token.

Подготовка:

Требуется зарегистрированное GitLab OAuth-приложение. GitLab ограничивает неавторизованные приложения с полем mcp и требует наличие api или read_api в качестве требований.
В GitLab инстансе: Admin Area > Applications (инстанс целиком) или User Settings > Applications (личные)
Создайте новое приложение.
Confidental: снять галочку
Scopes: api, read_api, read_user или укажите через GITLAB_OAUTH_SCOPES
Сохраните и скопируйте Application ID — это значение для GITLAB_OAUTH_APP_ID.

Как работает:

Пользователь добавляет URL MCP сервера в Claude.ai.
Claude.ai находит OAuth endpoints по /.well-known/oauth-authorization-server.
Claude.ai выполняет Dynamic Client Registration (POST /register). MCP сервер обрабатывает локально и выдает виртуальные client IDs для каждого клиента.
Claude.ai перенаправляет пользователя на страницу входа GitLab, используя зарегистрированное приложение.
Пользователь аутентифицируется, GitLab перенаправляет на https://claude.ai/api/mcp/auth_callback.
Claude.ai отправляет все MCP-запросы с Authorization: Bearer <token>.
Сервер валидирует токен в GitLab и сохраняет его по сессиям.

Настройка сервера:

docker run -d \
  -e STREAMABLE_HTTP=true \
  -e GITLAB_MCP_OAUTH=true \
  -e GITLAB_OAUTH_APP_ID="your-gitlab-oauth-app-client-id" \
  -e GITLAB_API_URL="https://gitlab.example.com/api/v4" \
  -e MCP_SERVER_URL="https://your-mcp-server.example.com" \
  -p 3002:3002 \
  zereight050/gitlab-mcp

Локальная разработка (разрешён HTTP):

MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL=true \
STREAMABLE_HTTP=true \
GITLAB_MCP_OAUTH=true \
GITLAB_OAUTH_APP_ID=your-gitlab-oauth-app-client-id \
MCP_SERVER_URL=http://localhost:3002 \
GITLAB_API_URL=https://gitlab.com/api/v4 \
node build/index.js

Настройки Claude.ai:

{
  "mcpServers": {
    "GitLab": {
      "url": "https://your-mcp-server.example.com/mcp"
    }
  }
}

headers здесь не требуются. Claude.ai получит токен через OAuth.

Переменные окружения:

переменная	обязательно	описание
GITLAB_MCP_OAUTH	да	активировать true
GITLAB_OAUTH_APP_ID	да	client ID предрегистрации GitLab OAuth-приложения
MCP_SERVER_URL	да	публичный HTTPS URL MCP-сервера
GITLAB_API_URL	да	URL GitLab API (например, https://gitlab.com/api/v4)
STREAMABLE_HTTP	да	обязательно true (SSE не поддерживается)
GITLAB_OAUTH_SCOPES	нет	список требуемых GitLab scope (через запятую). По умолчанию — api, read_api, read_user; приложение, которое вы регистрируете, должно иметь соответствующие scopes
OAUTH_REGISTER_RATE_LIMIT_PER_HOUR	нет	ограничение по IP на регистрацию клиентов в Dynamic Client Registration (по умолчанию 20/час). Если IDE открывает несколько окон, увеличьте лимит. Не связано с лимитами GitLab API
MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL	нет	разрешение на тестирование через локальный HTTP

Важно:

MCP OAuth работает только с Streamable HTTP (SSE несовместим).
Каждый пользовательский сеанс хранит свой OAuth-токен и полностью изолирован.
Срок действия сеанса, ограничение по скорости и лимит на количество сессий учитываются так же, как и в режиме REMOTE_AUTHORIZATION (см. SESSION_TIMEOUT_SECONDS, MAX_REQUESTS_PER_MINUTE, MAX_SESSIONS).
DCR rate limiting: POST /register ограничен по IP клиента с помощью OAUTH_REGISTER_RATE_LIMIT_PER_HOUR (по умолчанию 20/час). Это независимый лимит от лимитов GitLab API и лимитов на /mcp. Подробнее: environment-variables.md#oauth_register_rate_limit_per_hour.
Заголовочная аутентификация: если присутствуют заголовки Private-Token или JOB-TOKEN, OAuth-антифов не выполняется и raw токен напрямую используется в сессии. В рамках одного сервера можно совмещать OAuth и токены PAT/CI Job Token. Authorization: Bearer обрабатывается всегда как OAuth-токен. Для PAT используйте Private-Token.

Файлы навыков агента

Если AI‑агент поддерживает загрузку навыков/instructions (Claude Code, GitHub Copilot, Cursor и др.), можно использовать готовые файлы навыков из skills/gitlab-mcp/.

SKILL.md — краткое руководство: обзор инструментов, ключевые workflows, подсказки по параметрам
reference/ — подробные workflows для code review, Merge Request, issues, pipelines, vulnerability triage

Установить навыки через CLI:

npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill

Добавив директорию навыков в AI‑клиента, можно получать лучшие указания по использованию инструментов, чем ориентироваться лишь по полному списку инструментов.

Инструменты 🛠️

Полный перечень инструментов см. в английной README в разделе Tools: текущий сервер предоставляет инструменты для Merge Request, Issues, Pipelines, Deployments, Environments, Artifacts, Milestones, Wiki, Repositories, Releases, Users, Events, Work items, Webhooks, Code search, CI/CD variables, dependency proxy, vulnerability triage и GraphQL execution tools.

Заголовок и slug страниц Wiki

GitLab извлекает slug (URL, /-/wikis/<slug>) из названия wiki‑страницы. Поэтому передача параметра title в update_wiki_page / update_group_wiki_page может изменить имя страницы и её URL, что сломает существующие ссылки.

Чтобы сохранить URL и при этом изменить отображаемое название, не передавайте title, а сохраните отображаемое название в YAML front matter страницы и обновляйте содержимое:

---
title: Пользовательское отображаемое название
---

Текст страницы…

GitLab сохранит slug/URL без изменений и отобразит в UI заголовок из front matter. При повторном чтении используйте get_wiki_page с render_html: true, чтобы заполнить поле front_matter — фактическим значением будет всегда соответствовать slug.

Тесты 🧪

В проект включено всестороннее тестирование, включая удалённую аутентификацию.

# Полный набор тестов (API валидация + удалённая аутентификация)
npm test

# Только тесты удалённой аутентификации
npm run test:remote-auth

# Полный набор тестов, включая тесты readonly MCP
npm run test:all

# Только API валидация
npm run test:integration

Все тесты удалённой аутентификации используют mock‑GitLab сервер, поэтому реальные учётные данные GitLab не требуются.