gitlab-ci-mcp

MCP-сервер для GitLab CI/CD. Позволяет LLM-агенту (Claude Code, Cursor, OpenCode, DevX Agent и др.) работать с пайплайнами, заданиями, расписаниями, ветками, тегами, merge request'ами и файлами репозитория.

Python, FastMCP, транспорт stdio.

Работает с любым GitLab — SaaS gitlab.com или self-hosted / on-prem. Разработан с учетом корпоративных сетей: настраиваемая обработка NO_PROXY, опциональное отключение проверки SSL, ограничение области действия (scoping) для каждого проекта через переменные окружения.

Основные особенности дизайна

• Аннотации инструментов — каждый инструмент содержит readOnlyHint / destructiveHint / idempotentHint / openWorldHint, чтобы MCP-клиенты могли классифицировать операции (например, запрашивать подтверждение только для деструктивных действий, таких как gitlab_merge_mr, gitlab_delete_schedule).

• Структурированный вывод для каждого инструмента — каждый инструмент объявляет тип возвращаемого значения TypedDict, поэтому FastMCP автоматически генерирует outputSchema, и каждый результат содержит structuredContent наряду с предварительно отрендеренным блоком текста в формате markdown. Клиенты, умеющие отображать структурированные данные, используют их; агенты, предпочитающие компактный текст, получают markdown. Параметр response_format не требуется.

• Структурированные ошибки — ошибки аутентификации, 404, 403, 429 (превышение лимита запросов), 5xx и отсутствие переменных окружения преобразуются в понятные сообщения ToolError (например, "GitLab authentication failed… verify GITLAB_TOKEN has api scope") и возвращаются как результаты с isError=True.

• Валидация ввода Pydantic — каждый аргумент имеет типизированные ограничения (диапазоны, длины, литералы), автоматически экспортируемые как JSON Schema.

• Ограничение области действия проекта для каждого вызова — каждый инструмент принимает опциональный аргумент project_path, который переопределяет GITLAB_PROJECT_PATH для запросов между проектами.

• Пагинация — инструменты для получения списков возвращают блок pagination с полями page, total, has_more, next_page и подсказкой о следующей странице в футере markdown.

• Интеграция с контекстом MCP — gitlab_pipeline_health и gitlab_get_job_log являются async и отправляют логи info / события report_progress через контекст MCP, чтобы клиенты могли отображать индикаторы выполнения.

• Ресурсы MCP — gitlab://project/info и gitlab://project/ci-config дублируют распространенные запросы для клиентов, предпочитающих модель ресурсов, а не инструментов.

• Управление жизненным циклом — HTTP-сессии python-gitlab корректно закрываются при завершении работы сервера через хук жизненного цикла asynccontextmanager.

• Поиск по логам (grep) — gitlab_get_job_log принимает grep_pattern + grep_context (окружающие строки) для фильтрации CI-логов размером в мегабайты с помощью регулярных выражений, не загружая весь лог в контекст агента.

Модель потоков

FastMCP автоматически запускает синхронные инструменты в рабочем потоке (anyio.to_thread.run_sync), поэтому они не блокируют цикл событий asyncio — python-gitlab является синхронной библиотекой, и обертывание каждого вызова в asyncio.to_thread вручную было бы излишним. Инструменты, использующие контекст MCP (прогресс, информационные логи), написаны как async def и явно оборачивают вызовы python-gitlab с помощью asyncio.to_thread.

Возможности

23 инструмента, охватывающих повседневные задачи CI/CD:

Пайплайны gitlab_list_pipelines · gitlab_get_pipeline · gitlab_get_pipeline_jobs · gitlab_get_job_log · gitlab_trigger_pipeline · gitlab_retry_pipeline · gitlab_cancel_pipeline · gitlab_pipeline_health

Расписания gitlab_list_schedules · gitlab_create_schedule · gitlab_update_schedule · gitlab_delete_schedule

Ветки и теги gitlab_list_branches · gitlab_list_tags · gitlab_compare_branches

Merge request'ы gitlab_list_merge_requests · gitlab_get_merge_request · gitlab_get_merge_request_changes · gitlab_create_merge_request · gitlab_merge_mr

Репозиторий и проект gitlab_get_file · gitlab_list_repository_tree · gitlab_project_info

Отчет о состоянии пайплайна

gitlab_pipeline_health возвращает готовое к прочтению резюме за 7/30 дней:

Last 7d:  96.4%  up   | 27/28 success
Last 30d: 92.1%       | 105/114 success
Last 10:  success success success failed success ...

Удобно для дежурств / триажа: покажи health master за последние 7 дней.

Установка

Требуется Python 3.10+.

# via uvx (recommended)
uvx --from gitlab-ci-mcp gitlab-ci-mcp

# or via pip/pipx
pipx install gitlab-ci-mcp

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

Вся настройка осуществляется через переменные окружения:

Каждый инструмент принимает опциональный аргумент project_path, который переопределяет GITLAB_PROJECT_PATH для конкретного вызова — полезно для запросов между проектами.

Claude Code

Полное руководство: docs/claude-code.md — предварительные требования, два способа установки, настройка для нескольких проектов, self-hosted GitLab за корпоративным прокси, устранение неполадок, удаление.

Краткая версия:

claude mcp add gitlab uvx --from gitlab-ci-mcp gitlab-ci-mcp \
  --env GITLAB_URL=https://gitlab.example.com \
  --env GITLAB_TOKEN=glpat-xxxxxx \
  --env GITLAB_PROJECT_PATH=my-org/my-repo

Или в ~/.claude.json / .mcp.json проекта:

{
  "mcpServers": {
    "gitlab": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "gitlab-ci-mcp", "gitlab-ci-mcp"],
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "${GITLAB_TOKEN}",
        "GITLAB_PROJECT_PATH": "my-org/my-repo",
        "GITLAB_SSL_VERIFY": "true"
      }
    }
  }
}

Проверка:

claude mcp list
# gitlab: uvx --from gitlab-ci-mcp gitlab-ci-mcp - ✓ Connected

Cursor / OpenCode / DevX Agent

Аналогично — укажите в конфигурации MCP uvx --from gitlab-ci-mcp gitlab-ci-mcp с указанными выше переменными окружения. См. синтаксис конфигурации MCP для каждого конкретного инструмента.

Примеры запросов

что сломалось в последнем pipeline master

покажи health master за 7 дней для проекта my-org/other-repo

создай MR из feature/foo в master с title "feat: foo"

покажи содержимое .gitlab-ci.yml из master

Лимиты запросов и повторное использование соединений

GitLab устанавливает лимит запросов на пользователя (обычно 2000 запросов в час для REST API, настраивается администратором — см. /admin/application_settings/network в вашем экземпляре).

• Сервер кэширует одну HTTP-сессию python-gitlab на project_path, поэтому повторные вызовы инструментов для одного и того же проекта используют существующее соединение и не требуют повторной аутентификации.

• Инструменты для получения списков по умолчанию используют per_page=20, чтобы уложиться в небольшое количество запросов API за один вызов.

• Если вы получили ошибку 429 Too Many Requests, обработчик ошибок вернет понятное сообщение — подождите и попробуйте снова с большим значением per_page или меньшим количеством вызовов.

Self-hosted GitLab за корпоративным прокси

Если на вашем ноутбуке настроен локальный HTTP-прокси (например, http://127.0.0.1:3128 для доступа в интернет), а GitLab находится во внутренней сети, прокси перехватывает и блокирует внутренние запросы. Есть два варианта:

1. Установите GITLAB_NO_PROXY_DOMAINS — сервер добавит их в NO_PROXY при запуске и очистит HTTP_PROXY/HTTPS_PROXY из своего процесса, чтобы они не влияли на трафик GitLab.

2. Явно передайте пустые значения HTTP_PROXY="" и т.д. в секции env конфигурации MCP.

Разработка

git clone https://github.com/mshegolev/gitlab-ci-mcp
cd gitlab-ci-mcp
python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest

Запуск сервера напрямую (транспорт stdio, ожидает сообщения MCP из stdin):

GITLAB_URL=... GITLAB_TOKEN=... GITLAB_PROJECT_PATH=... gitlab-ci-mcp

Лицензия

MIT — см. LICENSE.

Благодарности

Построено на базе python-gitlab и MCP Python SDK.