MCP GitLab CrunchTools

Безопасный MCP-сервер (Model Context Protocol) для проектов GitLab, merge request'ов, задач, пайплайнов и поиска. Работает с любым экземпляром GitLab (gitlab.com, self-hosted или enterprise).

Обзор

Этот MCP-сервер разработан с учётом следующих принципов:

• Безопасен по умолчанию — комплексное моделирование угроз, проверка входных данных и защита токенов

• Без сторонних сервисов — работает локально через stdio, ваш API-токен никогда не покидает вашу машину

• Мультиинстансность — работает с gitlab.com, self-hosted GitLab или enterprise-экземплярами через настраиваемый URL

• Кроссплатформенность — работает на Linux, macOS и Windows

• Автоматическое обновление — GitHub Actions отслеживают CVE и обновляют зависимости

• Контейнеризация — доступен на quay.io/crunchtools/mcp-gitlab, построен на базовом образе Hummingbird Python

Related MCP server: gitlab-mcp-server

Соглашение об именах

Почему Hummingbird?

Образ контейнера построен на базовом образе Hummingbird Python из проекта Hummingbird, который обеспечивает:

• Минимальное количество CVE — собран с минимальным набором пакетов, что значительно снижает поверхность атаки

• Регулярные обновления — исправления безопасности применяются своевременно

• Оптимизация для Python — предварительно настроенное окружение Python с менеджером пакетов uv

• Готовность к продакшену — корректная обработка сигналов и настройки по умолчанию для непривилегированного пользователя

Возможности

Управление проектами (5 инструментов)

• list_projects — список проектов с фильтрацией и поиском

• get_project — получение деталей проекта по ID или пути

• list_project_branches — список веток репозитория

• get_project_branch — получение одной ветки

• list_project_commits — список коммитов с фильтрацией по дате/пути

Управление группами (3 инструмента)

• list_groups — список групп с фильтрацией

• get_group — получение деталей группы по ID или пути

• list_group_projects — список проектов в группе (с поддержкой подгрупп)

Merge Request'ы (7 инструментов)

• list_merge_requests — список MR по статусу, меткам, вехе

• get_merge_request — получение деталей MR

• create_merge_request — создание нового MR

• update_merge_request — обновление заголовка, описания, статуса, назначенных

• list_mr_notes — список комментариев к MR

• create_mr_note — добавление комментария к MR

• get_mr_changes — получение diff для MR

Задачи (6 инструментов)

• list_issues — список задач по статусу, меткам, вехе, назначенному

• get_issue — получение деталей задачи

• create_issue — создание новой задачи

• update_issue — обновление заголовка, описания, статуса, меток

• list_issue_notes — список комментариев к задаче

• create_issue_note — добавление комментария к задаче

Пайплайны (4 инструмента)

• list_pipelines — список CI/CD пайплайнов с фильтрацией по статусу

• get_pipeline — получение деталей пайплайна

• list_pipeline_jobs — список заданий в пайплайне

• get_job_log — получение лога задания

Поиск (2 инструмента)

• search_global — поиск по всем доступным ресурсам GitLab

• search_project — поиск в конкретном проекте

Установка

С помощью uvx (рекомендуется)

uvx mcp-gitlab-crunchtools

С помощью pip

pip install mcp-gitlab-crunchtools

С помощью контейнера

podman run -e GITLAB_TOKEN=your_token \
    quay.io/crunchtools/mcp-gitlab

Конфигурация

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

Создание персонального токена доступа GitLab

1. Перейдите к токенам доступа

   • Перейдите на https://gitlab.com/-/user_settings/personal_access_tokens

   • Или: Аватар > Настройки > Токены доступа

2. Создайте пользовательский токен

   • Имя: mcp-gitlab-crunchtools

   • Срок действия: установите подходящую дату (рекомендуется 90 дней)

   • Области: выберите области в зависимости от ваших потребностей

3. Выбор области

   Область	Уровень доступа	Возможности
   read_api	Только чтение	Просмотр проектов, задач, MR, пайплайнов
   api	Полный доступ	Все функции, включая создание и обновление

4. Скопируйте и сохраните токен

   • Скопируйте токен сразу (начинается с glpat-)

   • Надёжно храните его в менеджере паролей

Добавление в Claude Code

claude mcp add mcp-gitlab-crunchtools \
    --env GITLAB_TOKEN=your_token_here \
    -- uvx mcp-gitlab-crunchtools

Для self-hosted GitLab:

claude mcp add mcp-gitlab-crunchtools \
    --env GITLAB_TOKEN=your_token_here \
    --env GITLAB_URL=https://gitlab.example.com \
    -- uvx mcp-gitlab-crunchtools

Для версии в контейнере:

claude mcp add mcp-gitlab-crunchtools \
    --env GITLAB_TOKEN=your_token_here \
    -- podman run -i --rm -e GITLAB_TOKEN quay.io/crunchtools/mcp-gitlab

Примеры использования

Список ваших проектов

User: List my GitLab projects
Assistant: [calls list_projects with membership=true]

Просмотр merge request'ов

User: Show open merge requests for my-org/backend
Assistant: [calls list_merge_requests with project_id="my-org/backend"]

Создание задачи

User: Create an issue in my-org/backend titled "Fix login timeout"
Assistant: [calls create_issue with title="Fix login timeout"]

Проверка статуса пайплайна

User: Show failed pipelines for my-org/api
Assistant: [calls list_pipelines with status="failed"]

Поиск кода

User: Search for "authentication" in my-org/backend
Assistant: [calls search_project with scope="blobs"]

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

Этот сервер разработан с учётом безопасности как основного приоритета. См. SECURITY.md для:

• Модели угроз и векторов атак

• Архитектуры защиты в глубину

• Рекомендаций по обращению с токенами

• Правил проверки входных данных

• Аудита журналов

Ключевые функции безопасности

1. Защита токенов

   • Хранится как SecretStr (никогда не попадает в логи случайно)

   • Только через переменные окружения (никогда в файлах или аргументах)

   • Очищается из всех сообщений об ошибках

2. Проверка входных данных

   • Pydantic-модели для всех входных данных

   • Проверка символов по белому списку для ID проектов/групп

   • Предотвращение обхода путей

3. Усиление API

   • Принудительное использование HTTPS (кроме localhost)

   • Проверка TLS-сертификатов

   • Таймауты запросов (30 секунд)

   • Ограничение размера ответа (10 МБ)

4. Автоматическое сканирование CVE

   • GitHub Actions еженедельно сканируют зависимости

   • Сканирование безопасности контейнера с помощью Trivy

   • Анализ CodeQL для Python

Разработка

Настройка

git clone https://github.com/crunchtools/mcp-gitlab.git
cd mcp-gitlab
uv sync

Запуск тестов

uv run pytest

Линтинг и проверка типов

uv run ruff check src tests
uv run mypy src

Сборка контейнера

podman build -t mcp-gitlab .

Лицензия

AGPL-3.0-or-later

Вклад

Приветствуется! Пожалуйста, прочитайте SECURITY.md перед отправкой изменений, связанных с безопасностью.

Ссылки

• Документация GitLab REST API

• Документация FastMCP

• Спецификация MCP

• crunchtools.com