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

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

Важный нюанс - если у вас нет сложных кейсов вроде код-ревью по тредам, используйте 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 и в путь!

Промпт

Пробегись по моей системе и найди все установленные AI coding tools и IDE, которые поддерживают MCP: Claude Code, Claude Desktop, Cursor, Gemini CLI, Antigravity, Antigravity IDE, Codex CLI, Codex App, Cline, Roo Code, Continue, Windsurf, VS Code extensions и похожие инструменты.

Цель: настроить единый MCP-доступ к GitHub и GitLab так, чтобы все эти инструменты использовали один и тот же локально установленный MCP-сервер, а не тянули разные версии через npx.

Сначала найди реальные MCP-конфиги каждого инструмента и прочитай их формат. Не угадывай пути и не ломай существующие настройки. Проверь стандартные места:
- ~/.claude.json
- ~/.cursor/mcp.json
- ~/.gemini/settings.json
- ~/.gemini/config/mcp_config.json
- ~/.codex/config.toml
- Claude Desktop:
  - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  - Windows: %APPDATA%\Claude\claude_desktop_config.json
  - Windows MSIX/package: AppData\Local\Packages\Claude_*\LocalCache\Roaming\Claude\claude_desktop_config.json
- Codex App / package-local configs
- Cline / Roo Code / Continue / Windsurf / VS Code extension configs

Если один конфиг является symlink — не ломай symlink, меняй реальный target-файл.

Для GitLab self-hosted используй @zereight/mcp-gitlab. Если найдёшь @modelcontextprotocol/server-gitlab или npx -y @modelcontextprotocol/server-gitlab — замени: этот вариант часто ломается на schema/inputSchema validation.

Установи или проверь пакет:

npm install -g @zereight/mcp-gitlab

Найди реальный global npm path через:

npm root -g

И пропиши абсолютный путь к:

@zereight/mcp-gitlab/build/index.js

Базовая схема GitLab:

command: node
args: [абсолютный путь к @zereight/mcp-gitlab/build/index.js]
env:
  GITLAB_PERSONAL_ACCESS_TOKEN: <мой PAT>
  GITLAB_API_URL: https://<мой-gitlab-host>/api/v4

Важно: GITLAB_API_URL обязательно должен заканчиваться на /api/v4. Не используй официальный GitLab HTTP MCP /api/v4/mcp, если на self-hosted GitLab он не включён админами.

Для GitHub используй официальный github/github-mcp-server, а не старый @modelcontextprotocol/server-github.

Проверь официальный репозиторий:
https://github.com/github/github-mcp-server

Если GitHub MCP ещё не установлен, предложи лучший вариант установки для моей системы: локальный бинарь, Docker или другой официальный recommended-вариант.

Для GitHub настрой ограниченный набор toolsets, не включай всё подряд. Базовый набор:

context,repos,issues,pull_requests

По умолчанию включи read-only режим, если мне явно не нужны write-операции.

Для каждого найденного клиента запиши MCP в его родном формате:
- JSON для Claude Desktop / Cursor / Gemini
- TOML для Codex
- специальный формат для Antigravity, если он использует $typeName
- формат расширения, если это VS Code / Cline / Roo / Continue / Windsurf

Не коммить токены в проектные репозитории. Если конфиг проектный — предупреди меня. Если возможно — используй user-level config.

После настройки проверь:
- что MCP-сервер стартует
- что tools реально видны
- что нет ошибок schema validation
- что GitLab/GitHub отвечают на простые read-запросы

В конце дай отчёт:
1. какие AI-инструменты найдены
2. какие конфиги изменены
3. какой GitLab MCP используется
4. какой GitHub MCP используется
5. где лежит единый сервер
6. какие токены/scopes нужны
7. какие инструменты надо перезапустить
8. какие проблемы были исправлены

Важное ограничение: не делай опасных write-операций в GitHub/GitLab. Только настройка локальных MCP-конфигов и read-only проверка.

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

GitHub

@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

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

https://<gitlab.example.com>/api/v4/mcp

Документация: 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 не загружаются.

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

Invalid input: expected "object"
inputSchema.type

Суть проблемы: сервер отдаёт некорректную или неполную 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.

Плохо:

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-gitlab"]
}

Хорошо:

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

Установка GitLab MCP

npm install -g @zereight/mcp-gitlab

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

npm root -g

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

C:\Users\User\.npm-global\node_modules\@zereight\mcp-gitlab\build\index.js

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

~/.npm-global/node_modules/@zereight/mcp-gitlab/build/index.js

Установка GitHub MCP

Вариант 1 — Docker

docker pull ghcr.io/github/github-mcp-server

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

git clone https://github.com/github/github-mcp-server
cd github-mcp-server
go build -o github-mcp-server ./cmd/github-mcp-server

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

/path/to/github-mcp-server stdio

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

C:\tools\github-mcp-server.exe stdio

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

GitLab self-hosted

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": [
        "C:\\Users\\User\\.npm-global\\node_modules\\@zereight\\mcp-gitlab\\build\\index.js"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat_xxxxx",
        "GITLAB_API_URL": "https://gitlab.company.com/api/v4"
      }
    }
  }
}

Критично:

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

Правильно:

https://gitlab.company.com/api/v4

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

https://gitlab.company.com

GitHub.com

{
  "mcpServers": {
    "github": {
      "command": "C:\\tools\\github-mcp-server.exe",
      "args": ["stdio"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_xxxxx",
        "GITHUB_TOOLSETS": "context,repos,issues,pull_requests",
        "GITHUB_READ_ONLY": "1"
      }
    }
  }
}

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

GITHUB_HOST должен быть с https://

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

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

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

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

context,repos,issues,pull_requests

Для 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 -

~/.claude.json

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

claude mcp add gitlab \
  -e GITLAB_PERSONAL_ACCESS_TOKEN=glpat_xxxxx \
  -e GITLAB_API_URL=https://gitlab.company.com/api/v4 \
  -- node /path/to/@zereight/mcp-gitlab/build/index.js

Claude Desktop macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Claude Desktop Windows

%APPDATA%\Claude\claude_desktop_config.json

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

AppData\Local\Packages\Claude_*\LocalCache\Roaming\Claude\claude_desktop_config.json

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

Gemini CLI

~/.gemini/settings.json

Antigravity / Antigravity IDE

~/.gemini/config/mcp_config.json

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

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

"$typeName": "exa.cascade_plugins_pb.CascadePluginCommandTemplate"

Codex CLI

~/.codex/config.toml

Пример GitLab в TOML:

[mcp_servers.gitlab]
command = "node"
args = ['C:\Users\User\.npm-global\node_modules\@zereight\mcp-gitlab\build\index.js']

[mcp_servers.gitlab.env]
GITLAB_PERSONAL_ACCESS_TOKEN = "glpat_xxxxx"
GITLAB_API_URL = "https://gitlab.company.com/api/v4"

Пример GitHub в TOML:

[mcp_servers.github]
command = "C:\tools\github-mcp-server.exe"
args = ["stdio"]

[mcp_servers.github.env]
GITHUB_PERSONAL_ACCESS_TOKEN = "github_pat_xxxxx"
GITHUB_TOOLSETS = "context,repos,issues,pull_requests"
GITHUB_READ_ONLY = "1"

Cursor

~/.cursor/mcp.json

Пример:

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": [
        "C:\\Users\\User\\.npm-global\\node_modules\\@zereight\\mcp-gitlab\\build\\index.js"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat_xxxxx",
        "GITLAB_API_URL": "https://gitlab.company.com/api/v4"
      }
    }
  }
}

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

Проблема 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_PERSONAL_ACCESS_TOKEN
GITLAB_API_URL

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

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

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

Решение:

"GITHUB_TOOLSETS": "context,repos,issues,pull_requests"

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

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

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

"GITHUB_READ_ONLY": "1"

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

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

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

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

npm install -g @zereight/mcp-gitlab

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

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

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

Решение:

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

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

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

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

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

GitHub

GitLab

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

Установка GitLab MCP

Установка GitHub MCP

Вариант 1 — Docker

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

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

GitLab self-hosted

GitHub.com

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

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

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

Claude Code CLI -

Claude Desktop macOS

Claude Desktop Windows

Gemini CLI

Antigravity / Antigravity IDE

Codex CLI

Cursor

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

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

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

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

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

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

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

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

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

GitHub

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

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

Публикации