@mmtr-tech/gitlab-mcp

MCP-сервер для GitLab API. Даёт ИИ-клиентам (Cursor, Claude Desktop, Claude Code, OpenCode и др.) доступ к проектам, Merge Request'ам, Issues, веткам, тегам/релизам и CI/CD.

Протестирован на: GitLab 17.7.7 (self-hosted)
API: GitLab API v4 (13.x — 17.x+)

Требования

• Node.js >= 18
• Personal Access Token GitLab с scope api (для записи) или read_api (только чтение)

Подключение

Добавьте сервер в конфиг MCP-клиента. Переменные окружения обязательны.

Cursor

Settings → MCP или .cursor/mcp.json:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@mmtr-tech/gitlab-mcp"],
      "env": {
        "GITLAB_URL": "https://gitlab.yourdomain.com",
        "GITLAB_TOKEN": "glpat-your_personal_access_token",
        "GITLAB_SSL_VERIFY": "true"
      }
    }
  }
}

Claude Desktop

Файл конфигурации:

• Linux: ~/.config/Claude/claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@mmtr-tech/gitlab-mcp"],
      "env": {
        "GITLAB_URL": "https://gitlab.yourdomain.com",
        "GITLAB_TOKEN": "glpat-your_personal_access_token",
        "GITLAB_SSL_VERIFY": "true"
      }
    }
  }
}

OpenCode

Конфиг: opencode.json / opencode.jsonc (проект или глобальный). Формат отличается от Cursor — см. доку OpenCode.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gitlab": {
      "type": "local",
      "command": ["npx", "-y", "@mmtr-tech/gitlab-mcp"],
      "enabled": true,
      "environment": {
        "GITLAB_URL": "https://gitlab.yourdomain.com",
        "GITLAB_TOKEN": "glpat-your_personal_access_token",
        "GITLAB_SSL_VERIFY": "true"
      },
      "timeout": 60000
    }
  }
}

Замечания:

• Поля: environment (не env), один массив command (не command + args).
• Таймаут загрузки tools по умолчанию 5 с; первый npx часто не успевает — укажите timeout (мс), как выше.
• После правки конфига перезапустите OpenCode Desktop.

Claude Code и другие клиенты

Тот же блок command / args / env в .mcp.json (или аналоге клиента).

После смены конфига перезапустите клиент (или Reload Window), чтобы подтянуть список tools.

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

| Переменная | Обязательная | Описание | |------------|--------------|----------| | GITLAB_URL | да | Базовый URL инстанса, например https://gitlab.com или ваш self-hosted | | GITLAB_TOKEN | да | Personal Access Token | | GITLAB_SSL_VERIFY | нет | true по умолчанию; false — для самоподписанного сертификата | | GITLAB_TIMEOUT_MS | нет | Таймаут HTTP-запросов в мс (по умолчанию 30000) |

Возможности (84 инструмента)

• Репозитории: поиск проектов, детали, смена default branch, чтение файла, дерево каталога, поиск по коду, labels
• Merge settings: get/update метода merge, squash, проверки pipeline/discussions перед merge
• Merge Requests: список/детали, diff, коммиты, комментарии и треды, approve, создание/обновление/merge/rebase/close/reopen, inline-комментарии
• Issues: список, детали, создание, update, close/reopen, комментарии, список notes
• Ветки и коммиты: CRUD веток, история и diff коммитов
• Protected branches: list/get/protect/update/unprotect (уровни доступа, force push, флаг CODEOWNERS)
• Protected tags: list/get/protect/unprotect
• Approval rules: list/create/update/delete правил аппрува MR (часто Premium/EE)
• Members: list/add/edit/remove участников проекта
• Tags & Releases: CRUD тегов; releases list/get/create/update/delete
• CI/CD: пайплайны (фильтры ref/sha), джобы, логи (tail_lines), trigger/cancel/retry/play, пайплайны MR
• Прочее: текущий пользователь (get_current_user)

Замечания:

• search_code нужен Advanced Search / Zoekt на инстансе; иначе вернётся понятная ошибка.
• Крупные ответы (get_mr_diff, get_job_trace, содержимое файлов и др.) обрезаются по max_chars (по умолчанию ~80 000). Для длинных логов используйте tail_lines.
• Tools для protected branches/tags, merge settings, members и default branch требуют Maintainer+ и токен со scope api.
• Уровни доступа (ветки/теги): 0 No one, 30 Developer, 40 Maintainer.
• Уровни участников: 10 Guest, 20 Reporter, 30 Developer, 40 Maintainer, 50 Owner.
• Approval rules проекта могут требовать GitLab Premium/EE.

Лицензия

MIT

На странице npm отображается английский README.md. Этот файл — русская версия; он лежит в установленном пакете (node_modules/@mmtr-tech/gitlab-mcp/README.ru.md).