@alexsarrell/gitlab-mcp-server

MCP (Model Context Protocol) сервер для self-hosted GitLab. Позволяет AI-ассистентам (Claude Code, Cursor, Windsurf и др.) работать с GitLab через стандартный MCP-протокол.

Разработан для gitlab.just-ai.com, но работает с любым GitLab инстансом (self-hosted или gitlab.com).

Возможности

• 49 MCP tools — проекты, файлы, MR, issues, пайплайны, коммиты, ветки, теги, группы, раннеры, окружения, реестр образов и др.
• Настраиваемые политики доступа — RBAC + ABAC через Casbin, YAML-профили с наследованием
• Безопасность — hardcoded deny list опасных операций, secret detection в output, deny-list файлов
• Rate limiting — per-session, burst allowance, лимиты на тяжёлые операции
• Audit logging — structured JSON в stderr, неотключаемый
• Zero-config режим — работает только с env vars, без YAML файла

Быстрый старт

Claude Code / Claude Desktop

Добавьте в ~/.claude.json (или claude_desktop_config.json):

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@alexsarrell/gitlab-mcp-server"],
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_MCP_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Готово. Сервер стартует с дефолтным профилем — все read/write операции разрешены, secret detection включён.

С YAML-конфигом (гранулярные политики)

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@alexsarrell/gitlab-mcp-server"],
      "env": {
        "GITLAB_MCP_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_MCP_CONFIG": "/path/to/gitlab-mcp.config.yaml"
      }
    }
  }
}

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

| Переменная | Обязательная | Описание | |-----------|-------------|----------| | GITLAB_MCP_TOKEN | Да | GitLab Personal/Project/Group Access Token | | GITLAB_URL | Нет* | URL GitLab инстанса (e.g. https://gitlab.example.com) | | GITLAB_MCP_CONFIG | Нет | Путь к YAML конфигу |

* Обязательна в zero-config режиме (без YAML файла). В YAML конфиге задаётся через gitlab.url.

Токены

Рекомендуемые scopes для токена:

| Scope | Для чего | |-------|----------| | read_api | Чтение проектов, MR, issues, пайплайнов | | read_repository | Чтение файлов из репозиториев | | write_repository | Создание веток | | api | Полный доступ (write-операции: MR, issues, comments, pipelines) |

Минимальный набор для read-only: read_api + read_repository.

MCP Tools (49)

Проекты и группы

| Tool | Описание | |------|----------| | project_list | Список проектов (поиск, пагинация) | | project_info | Детали проекта | | group_list | Список групп | | group_info | Детали группы | | member_list | Участники проекта или группы |

Файлы и код

| Tool | Описание | |------|----------| | file_read | Чтение файла из репо (с блокировкой .env, .pem и др.) | | file_list | Содержимое директории | | file_tree | Рекурсивное дерево файлов | | search_code | Поиск по коду |

Merge Requests

| Tool | Описание | |------|----------| | mr_list | Список MR (фильтр по state, поиск) | | mr_get | Детали MR | | mr_diff | Diff MR (изменённые файлы) | | mr_create | Создание MR | | mr_update | Обновление MR (title, description, labels, assignees) | | mr_merge | Merge MR (squash, remove source branch) | | mr_approve | Approve MR | | mr_discussions | Discussion threads MR (с resolved-статусом) |

Issues

| Tool | Описание | |------|----------| | issue_list | Список issues (фильтр, поиск, labels) | | issue_get | Детали issue | | issue_create | Создание issue | | issue_update | Обновление issue (title, labels, state, assignees) | | search_issues | Поиск по issues | | search_mrs | Поиск по MR |

Комментарии

| Tool | Описание | |------|----------| | comment_list | Комментарии к MR или issue | | comment_create | Новый комментарий (markdown) | | comment_reply | Ответ на discussion thread в MR |

CI/CD

| Tool | Описание | |------|----------| | pipeline_status | Статус пайплайна + все джобы и стейджи | | pipeline_logs | Логи CI-джобы (secrets автоматически маскируются) | | pipeline_trigger | Запуск пайплайна (с переменными) | | pipeline_retry | Перезапуск упавшего пайплайна | | pipeline_cancel | Отмена пайплайна | | ci_lint | Валидация .gitlab-ci.yml | | runner_list | Список CI-раннеров проекта (статус, теги) | | variable_list | CI/CD переменные (только ключи, без значений!) |

Git (коммиты, ветки, теги)

| Tool | Описание | |------|----------| | commit_list | История коммитов (фильтр по ветке, файлу) | | commit_get | Детали коммита (автор, stats) | | commit_diff | Diff коммита | | branch_list | Список веток | | branch_create | Создание ветки | | branch_delete | Удаление ветки | | tag_list | Список тегов | | tag_create | Создание тега | | label_list | Метки проекта | | label_create | Создание метки |

Инфраструктура

| Tool | Описание | |------|----------| | environment_list | Окружения (staging, production) | | environment_get | Детали окружения + последний деплой | | registry_list | Container Registry — репозитории образов | | registry_tags | Теги (версии) образов в реестре | | event_list | Лента активности проекта (pushes, MR, comments) |

Конфигурация (YAML)

Пример конфига с политиками доступа:

version: "1"

gitlab:
  url: "https://gitlab.example.com"

defaults:
  role: reader

profiles:
  reader:
    tools:
      allow: ["project_*", "file_*", "mr_list", "mr_get", "mr_diff",
              "issue_*", "search_*", "pipeline_status", "pipeline_logs",
              "comment_list", "branch_list", "label_list", "commit_*",
              "tag_list", "group_*", "member_*", "runner_*",
              "environment_*", "registry_*", "variable_*", "event_*"]

  contributor:
    extends: reader
    tools:
      allow: ["mr_create", "mr_update", "issue_create", "issue_update",
              "comment_create", "comment_reply", "pipeline_trigger",
              "branch_create", "label_create", "ci_lint", "tag_create"]

  maintainer:
    extends: contributor
    tools:
      allow: ["mr_merge", "mr_approve", "branch_delete",
              "pipeline_retry", "pipeline_cancel"]

policies:
  # Все проекты группы — contributor
  - match: "group:my-team/**"
    profile: contributor

  # Инфра-проекты — только чтение
  - match: "group:my-team/infra/**"
    profile: reader

  # Core-проект — полный доступ
  - match: "project:my-team/platform/core"
    profile: maintainer

  # Секретный проект — запрет на чтение файлов
  - match: "project:my-team/infra/secrets"
    profile: reader
    tools:
      deny: ["file_read"]

rate_limits:
  per_session: 60        # запросов в минуту
  per_token: 120         # агрегированно по всем сессиям
  burst_multiplier: 2    # допустимый burst
  burst_window_sec: 10
  heavy_ops:
    "pipeline_trigger": 10   # в час
    "mr_create": 20          # в час

security:
  secret_detection: true
  denied_file_patterns:
    - ".env*"
    - "*.pem"
    - "*.key"
    - "*secret*"
    - "*credential*"
    - "id_rsa*"

Наследование политик

• Профили поддерживают extends — contributor наследует все права reader
• Приоритет: project policy > group policy > defaults
• deny всегда побеждает allow на любом уровне
• MCP политики могут только сужать права GitLab-токена, не расширять

Безопасность

Запрещённые операции (hardcoded, не настраивается)

Эти операции заблокированы всегда, независимо от конфигурации:

• Удаление проектов и групп
• Transfer проекта между группами
• Экспорт проекта
• Форк в чужой namespace
• Управление пользователями
• Системные admin-настройки
• SSH-ключи и deploy keys с write-доступом

Secret Detection

Автоматическая маскировка секретов в output:

• GitLab PAT (glpat-*)
• GitLab Deploy Tokens (gldt-*)
• Private keys (PEM)
• AWS Access Keys (AKIA*)
• Пароли в URL
• GitHub tokens

Секреты заменяются на [REDACTED:тип], а не блокируются — AI видит, что секрет был, но не видит значение.

Запрещённые файлы

По умолчанию блокируется чтение: .env*, *.pem, *.key, *secret*, *credential*, id_rsa*, kubeconfig.

CI/CD переменные

Tool variable_list возвращает только ключи и метаданные (protected, masked), никогда не возвращает значения.

Audit Logging

Каждое действие логируется в stderr как structured JSON:

{
  "timestamp": "2026-04-09T12:00:00.000Z",
  "level": "warn",
  "session_id": "sess_abc123",
  "tool": "mr_create",
  "project": "my-team/platform/core",
  "params": {"source_branch": "feature/x", "target_branch": "main"},
  "result": "success",
  "duration_ms": 342
}

Уровни: info (read), warn (write), error (ошибки), critical (denied).

Разработка

git clone [email protected]:secretary/ai-generated/gitlab-mcp-server.git
cd gitlab-mcp-server
npm install
npm test          # 176 тестов
npm run lint      # TypeScript type check
npm run build     # Сборка в dist/
npm run dev       # Запуск в dev-режиме (tsx)

Стек

• TypeScript 5.x + Node.js 20+
• @modelcontextprotocol/sdk — MCP протокол
• @gitbeaker/rest — GitLab API клиент
• casbin — Policy engine (RBAC + ABAC)
• vitest — Тесты
• tsup — Сборка

Лицензия

MIT