MCP для GitHub + GitLab: инженерный гайд 2026

MCP для GitHub + GitLab: инженерный гайд 2026

Habr AI

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

Важный нюанс - если у вас нет сложных кейсов вроде код-ревью по тредам, используйте CLI и все.

Всё, что нужно знать перед настройкой: токены, пакеты, конфиги, нюансы, проблемы и безопасный универсальный сетап для Claude Code CLI, Claude Desktop, Codex CLI, Gemini CLI, Antigravity, Codex, Cursor и прочего.

Быстрый старт: токены + промпт для автонастройки

Перед настройкой MCP нужны access tokens.

GitHub token брать здесь:https://github.com/settings/tokens/new

Обычно достаточно прав:

  • repo- если нужны приватные репозитории;
  • public_repo- если только публичные;
  • read:org- если надо видеть org/team metadata;
  • workflow- только если MCP должен работать с GitHub Actions.

GitLab token брать здесь:https://gitlab.twinby.tech/-/user_settings/personal\_access\_tokens

Для GitLab MCP обычно нужны:

  • read_api
  • read_repository

Если нужны write-операции:

  • api
  • write_repository

Лучше начать с read-only сценария (давать только читать и не позволять вносить изменения), не надо выдавать лишнего.

Промпт: дайте это любой AI-системе и скажите делай

Перед ручной настройкой можно просто скопировать промпт ниже в Claude Code / Codex / Gemini / Cursor / Antigravity / любую другую AI coding-систему, у которой есть доступ к терминалу и файловой системе, --yolo и в путь!

Какие пакеты существуют

@modelcontextprotocol/server-githubСтарый пакет от Anthropic/MCP-org. Может работать, но сейчас это не лучший выбор: устаревший подход, меньше контроля, хуже история с поддержкой.

github/github-mcp-serverОфициальный MCP-сервер от GitHub.

Репозиторий:https://github.com/github/github-mcp-server

Документация:https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp-in-your-ide/set-up-the-github-mcp-server

Официальный GitLab MCP HTTP endpoint

Документация:https://docs.gitlab.com/user/gitlab_duo/model_context_protocol/mcp_server/

Но для self-hosted GitLab есть важный нюанс: официальный GitLab MCP работает только если на инстансе включены нужные GitLab Duo / beta / MCP-фичи. На обычном корпоративном self-hosted GitLab этого часто нет.

@modelcontextprotocol/server-gitlabЛучше не использовать. На практике может ломаться на ошибках schema validation / inputSchema validation. Типичный симптом: MCP вроде подключается, но tools не загружаются.

Пример ошибки:

Суть проблемы: сервер отдаёт некорректную или неполную JSON Schema для tools, и современные MCP-клиенты отказываются это грузить.

@zereight/mcp-gitlabПрактический выбор для self-hosted GitLab без включённого официального MCP.

Репозиторий:https://github.com/zereight/gitlab-mcp

Пакет:https://www.npmjs.com/package/@zereight/mcp-gitlab

Почему он:

  • работает через обычный Personal Access Token
  • поддерживает self-hosted GitLab черезGITLAB_API_URL
  • работает со stdio, SSE, Streamable HTTP
  • есть примеры для Claude Code, Codex, Antigravity, Cursor, Cline, Roo Code и других клиентов
  • умеет issues, merge requests, pipelines, wiki, releases, tags, milestones
  • schema-баги уже фиксились, проект живой

Главная идея настройки

Не надо в каждом инструменте поднимать свой отдельный MCP.

  1. Ставим MCP один раз глобально.
  2. Во все клиенты прописываем один и тот жеnode path/to/server.jsили один и тот же бинарь.
  3. Обновляем централизованно.

Установка GitLab MCP

Проверить путь:

Типичный путь на Windows:

Типичный путь на macOS/Linux:

Установка GitHub MCP

Вариант 1 — Docker

Вариант 2 — локальный бинарь

Потом во все клиенты прописывается один и тот же бинарь:

Для Windows, например:

Единый JSON-конфиг для большинства клиентов

GitLab self-hosted

Правильно:

Неправильно:

GitHub.com

Критично для GitHub Enterprise:

Почему важно ограничивать GitHub tools

У GitHub MCP много tools. Если включить всё, агент получает огромный список возможностей, а это:

  • больше токенов на каждую сессию
  • хуже tool choice
  • больше шанс, что агент выберет не тот инструмент
  • больше риск случайных write-операций
  • быстрее упираетесь в лимиты

Минимальный нормальный набор:

Для CI/CD можно добавить actions. Для security code_security,dependabot (крутая штука)

Read-only режим — почти всегда включать по умолчанию

Для GitHub: “GITHUB_READ_ONLY”: “1” или аргумент github-mcp-server --read-only stdio.

Это убирает write-tools. Агент сможет читать репозитории, issues, PR, workflows, но не сможет случайно создать issue, изменить PR, удалить файл или поменять настройки.

Для GitLab через@zereight/mcp-gitlabтоже лучше начинать с read-only подхода: отдельный токен с минимальными scopes, без write-доступа, если он не нужен.

Где лежат конфиги

Claude Code CLI -

Добавление через CLI:

Claude Desktop macOS

Claude Desktop Windows

Но есть важный нюанс с Windows/MSIX: иногда приложение реально читает конфиг из package-local пути, например:

Если “Edit Config” открыл один файл, а MCP не появляется — ищите второй реальный конфиг.

Gemini CLI

Antigravity / Antigravity IDE

В некоторых установкахantigravityиantigravity-ideмогут быть symlink на один общий файл.

Для Antigravity может быть нужно поле:

Пример GitLab в TOML:

Пример GitHub в TOML:

Частые проблемы

Проблема 1: MCP “подключился”, но tools пустые

  • сломанная schema tools
  • старый пакет
  • клиент стал строже валидировать JSON Schema
  • используется@modelcontextprotocol/server-gitlab
  • заменить на@zereight/mcp-gitlab
  • не использовать старый@modelcontextprotocol/server-gitlab
  • проверить/mcpили MCP logs

Проблема 2: GitLab self-hosted не открывает /api/v4/mcp

Причина: официальный GitLab MCP не включён на инстансе.

  • либо просить админа включить GitLab Duo/MCP/beta features
  • либо использовать локальный@zereight/mcp-gitlabс PAT

Проблема 3: GitLab 401 Unauthorized

Проверить:

ОсобенноGITLAB_API_URL: должен быть/api/v4.

Также проверить scopes токена.

Проблема 4: GitHub MCP жрёт контекст и лимиты

Не включатьall, если не надо.

Проблема 5: агент может делать write-операции

Решение для GitHub:

Для GitLab — отдельный read-only PAT или максимально ограниченный токен.

Проблема 6: разные клиенты используют разные версии MCP

Решение: не использоватьnpx -yв каждом конфиге.

Ставим один раз:

И везде прописываем абсолютный путь к одномуbuild/index.js.

Для GitHub — один Docker image tag или один локальный бинарь.

Проблема 7: после правки конфига ничего не изменилось

  • Claude Desktop перезапустить полностью
  • Cursor перезапустить
  • Antigravity перезапустить
  • Gemini/Codex иногда перечитывают конфиг только при новом запуске
  • Claude Code можно проверить черезclaude mcp list

Рекомендованный итоговый сетап

GitLab self-hosted без официального MCP

GitLab self-hosted с официально включённым MCP

MCP мощная штука, но по факту это дать агенту API-ключи от для REST запросов. Ничего интересного.

Читать оригинал