Простой

8 мин

9.3K

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

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

Хорошо:

1. Ставим MCP один раз глобально.

2. Во все клиенты прописываем один и тот же node path/to/server.js или один и тот же бинарь.

3. Обновляем централизованно.

Установка 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

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

GitHub

github/github-mcp-server
local stdio
GITHUB_TOOLSETS=context,repos,issues,pull_requests
GITHUB_READ_ONLY=1

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

@zereight/mcp-gitlab
local stdio
GITLAB_API_URL=https://gitlab.company.com/api/v4
GITLAB_PERSONAL_ACCESS_TOKEN=glpat_xxxxx

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

https://gitlab.company.com/api/v4/mcp
HTTP transport
OAuth flow

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