@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) |

Возможности (57 инструментов)

• Репозитории: поиск проектов, детали, смена default branch, чтение файла, дерево каталога, поиск по коду
• Merge Requests: список/детали, diff, коммиты, комментарии и треды, approve, создание/обновление/merge/rebase/close/reopen, inline-комментарии
• Issues: список, детали, создание, close/reopen, комментарии
• Ветки и коммиты: CRUD веток, история и diff коммитов
• Protected branches: list/get/protect/update/unprotect (уровни доступа + force push)
• Tags & Releases: теги и GitLab Releases
• CI/CD: пайплайны, джобы, логи, retry
• Прочее: текущий пользователь (get_current_user)

Замечания:

• search_code нужен Advanced Search / Zoekt на инстансе; иначе вернётся понятная ошибка.
• Крупные ответы (get_mr_diff, get_job_trace, содержимое файлов и др.) обрезаются по max_chars (по умолчанию ~80 000).
• Tools для protected branches и default branch требуют Maintainer+ и токен со scope api.
• Уровни доступа: 0 No one, 30 Developer, 40 Maintainer.

Лицензия

MIT

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