gitlab-ci-mcp

GitLab CI/CD용 MCP 서버입니다. LLM 에이전트(Claude Code, Cursor, OpenCode, DevX Agent 등)가 파이프라인, 작업, 스케줄, 브랜치, 태그, 병합 요청 및 저장소 파일과 상호작용할 수 있게 합니다.

Python, FastMCP, stdio 전송을 사용합니다.

모든 GitLab(SaaS gitlab.com 또는 자체 호스팅/온프레미스)과 작동합니다. 기업 네트워크 환경을 고려하여 설계되었으며, NO_PROXY 처리, 선택적 SSL 검증 토글, 환경 변수를 통한 프로젝트별 범위 지정 기능을 제공합니다.

주요 설계 특징

• 도구 주석 — 모든 도구는 readOnlyHint / destructiveHint / idempotentHint / openWorldHint를 포함하여 MCP 클라이언트가 작업을 분류할 수 있도록 합니다(예: gitlab_merge_mr, gitlab_delete_schedule과 같은 파괴적 작업 시에만 확인 요청).

• 모든 도구의 구조화된 출력 — 각 도구는 TypedDict 반환 타입을 선언하므로 FastMCP가 자동으로 outputSchema를 생성하며, 모든 결과는 미리 렌더링된 마크다운 텍스트 블록과 함께 structuredContent를 포함합니다. 구조화된 데이터를 렌더링할 수 있는 클라이언트는 이를 사용하고, 간결한 텍스트를 선호하는 에이전트는 마크다운을 사용합니다. response_format 매개변수가 필요 없습니다.

• 구조화된 오류 — 인증, 404, 403, 429(속도 제한), 5xx, 누락된 환경 변수 오류는 실행 가능한 ToolError 메시지(예: "GitLab 인증 실패… GITLAB_TOKEN에 api 범위가 있는지 확인하세요")로 변환되어 isError=True 결과로 표시됩니다.

• Pydantic 입력 검증 — 모든 인수는 JSON Schema로 자동 노출되는 타입 제약 조건(범위, 길이, 리터럴)을 가집니다.

• 호출별 프로젝트 범위 지정 — 모든 도구는 교차 프로젝트 쿼리를 위해 GITLAB_PROJECT_PATH를 재정의하는 선택적 project_path를 허용합니다.

• 페이지네이션 — 목록 도구는 page, total, has_more, next_page가 포함된 pagination 블록과 마크다운 푸터의 다음 페이지 힌트를 반환합니다.

• MCP 컨텍스트 통합 — gitlab_pipeline_health 및 gitlab_get_job_log는 async로 작동하며 MCP 컨텍스트를 통해 info 로그 / report_progress 이벤트를 발생시켜 클라이언트가 진행률 표시줄을 표시할 수 있게 합니다.

• MCP 리소스 — gitlab://project/info 및 gitlab://project/ci-config는 도구보다 리소스 모델을 선호하는 클라이언트를 위해 일반적인 조회 기능을 미러링합니다.

• 수명 주기 관리 — python-gitlab HTTP 세션은 asynccontextmanager 수명 주기 훅을 통해 서버 종료 시 깔끔하게 닫힙니다.

• 로그 grep — gitlab_get_job_log는 전체 추적을 에이전트 컨텍스트로 가져오지 않고도 메가바이트 단위의 CI 로그를 정규식으로 필터링할 수 있도록 grep_pattern + grep_context(주변 줄)를 허용합니다.

스레딩 모델

FastMCP는 동기식 도구를 작업자 스레드(anyio.to_thread.run_sync)에서 자동으로 실행하므로 asyncio 이벤트 루프를 차단하지 않습니다. python-gitlab은 동기식 라이브러리이며 모든 호출을 직접 asyncio.to_thread로 감싸는 것은 번거로운 작업입니다. MCP 컨텍스트(진행률, 정보 로그)를 활용하는 도구는 async def로 작성되며 python-gitlab 호출을 asyncio.to_thread로 명시적으로 감쌉니다.

기능

일상적인 CI/CD 작업을 다루는 23개의 도구:

파이프라인 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

병합 요청 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

구성

모든 구성은 환경 변수를 통해 이루어집니다:

모든 도구는 호출 시 GITLAB_PROJECT_PATH를 재정의하는 선택적 project_path 인수를 허용하며, 이는 교차 프로젝트 쿼리에 유용합니다.

Claude Code

전체 가이드: docs/claude-code.md — 필수 조건, 두 가지 설치 경로, 다중 프로젝트 설정, 기업 프록시 뒤의 자체 호스팅 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은 사용자별 속도 제한을 적용합니다(일반적으로 REST API의 경우 시간당 2000회 요청, 관리자가 구성 가능 — 인스턴스의 /admin/application_settings/network 참조).

• 서버는 project_path당 하나의 python-gitlab HTTP 세션을 캐시하므로, 동일한 프로젝트에 대한 반복적인 도구 호출은 연결을 재사용하며 매번 재인증하지 않습니다.

• 목록 도구는 API 요청 수를 적게 유지하기 위해 기본적으로 per_page=20을 사용합니다.

• 429 Too Many Requests 오류가 발생하면 오류 핸들러가 실행 가능한 메시지를 반환합니다. 잠시 기다린 후 더 큰 per_page를 사용하거나 호출 횟수를 줄여 다시 시도하세요.

기업 프록시 뒤의 자체 호스팅 GitLab

노트북에 로컬 HTTP 프록시(예: 기업 웹 액세스를 위한 http://127.0.0.1:3128)가 있지만 GitLab이 인트라넷에 있는 경우, 프록시가 내부 요청을 가로채서 차단할 수 있습니다. 두 가지 옵션이 있습니다:

1. GITLAB_NO_PROXY_DOMAINS 설정 — 서버가 시작 시 이를 NO_PROXY에 추가하고 자체 프로세스에서 HTTP_PROXY/HTTPS_PROXY를 지워 GitLab 트래픽에 영향을 주지 않도록 합니다.

2. MCP env 섹션에서 HTTP_PROXY="" 등을 명시적으로 비워 전달합니다.

개발

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를 기반으로 구축되었습니다.