GitLab MCP

GitLab MCP는 하네스 중립적인 Model Context Protocol 서버이자 GitLab 저장소 작업을 위한 공유 Agent Skills입니다. Codex, Claude Code, Cline, Pi는 동일한 표준 MCP 코어의 지원 배포판이며, 별도의 GitLab 구현이 아닙니다. ChatGPT는 원격 Streamable HTTP 배포를 통해 동일한 코어를 사용할 수 있습니다.

이 프로젝트가 제공하는 것:

• 자체 포함된 GitLab MCP 서버(타입화된 도구 포함);

• 일반적인 $gitlab 스킬;

• 미해결 머지 리퀘스트 토론을 위한 $gl-address-comments 스킬;

• 파이프라인 및 작업 진단을 위한 $gl-fix-ci 스킬;

• 브랜치, 커밋, 드래프트, 머지 리퀘스트 전달을 위한 $gl-publish 스킬;

• GitLab 네이티브 러너, CI 린트, 거버넌스, 태그, 릴리스, 파이프라인 스케줄 워크플로우 및 시크릿 안전 프로젝트/그룹 CI/CD 변수 관리;

• 동일한 표준 코어와 Agent Skills을 재사용하는 경량 Codex, Claude Code, Cline, Pi 배포판; 그리고

• ChatGPT 배포를 위한 무상태 Streamable HTTP 전송 및 OAuth 보호 리소스 메타데이터.

시작하기

문서 색인은 전체 사용자, 운영자, 개발자, 보안, 호환성 및 릴리스 문서 세트를 연결합니다.

Related MCP server: GitLab MCP Server

빠른 시작

로컬 소스 설치의 경우 Node.js 22 이상을 사용한 후 표준 MCP 코어를 빌드하고 검증하십시오:

npm.cmd ci
npm.cmd test
npm.cmd run build

하네스와 일치하는 어댑터를 선택하십시오. 지원되는 네 가지 어댑터 모두 동일하게 빌드된 MCP 번들과 표준 Agent Skills을 사용합니다.

Codex의 경우 이 저장소를 신뢰할 수 있는 로컬 마켓플레이스에 추가하고 gitlab 플러그인을 설치한 후 Codex를 재시작하거나 새로 고치십시오. Codex를 실행하는 환경에서 인스턴스 URL과 토큰을 구성하십시오:

$env:GITLAB_URL = "https://gitlab.example.com"
$env:GITLAB_TOKEN = "<token>"

새 대화를 시작하고 Codex에게 연결을 확인하도록 요청하십시오. 예:

Use GitLab to tell me which account and instance are connected.

Claude Code 사용자는 네이티브 플러그인 배포판을 로드할 수 있으며, 동일한 MCP 서버와 표준 Agent Skills을 번들로 제공합니다. Claude Code 어댑터 가이드에서 패키지 검증, --plugin-dir 로딩 및 마켓플레이스 호환 레이아웃을 확인하십시오.

Cline 사용자는 stdio를 통해 동일한 표준 MCP 번들을 사용할 수 있으며, 별도의 GitLab 구현 없이 표준 Agent Skills을 설치할 수 있습니다. Cline 어댑터 가이드에서 IDE 및 CLI 설정을 확인하십시오.

Pi 사용자는 전용 Pi 패키지를 설치할 수 있으며, 얇은 stdio 브리지를 통해 표준 MCP 도구 인벤토리를 등록하고 동일한 Agent Skills을 노출합니다. Pi 어댑터 가이드에서 패키지 설치, 런타임 종속성 처리 및 브리지 제한 사항을 확인하십시오.

사용자 가이드에서 최소 권한 토큰 지침, 일반적인 GitLab 워크플로우 및 ChatGPT HTTP 배포를 확인하십시오.

요구 사항

• Node.js 22 이상

• GitLab.com, GitLab Dedicated 또는 자체 관리 GitLab 인스턴스

• 로컬 stdio 사용의 경우, 수행하려는 작업에 필요한 최소 범위의 GitLab 토큰

빌드 및 검증

npm.cmd install
npm.cmd test
npm.cmd run adapters:check
npm.cmd run check:bundle
npm.cmd run build
npm.cmd run validate:codex
npm.cmd run validate:claude
npm.cmd run validate:cline
npm.cmd run validate:pi
npm.cmd run check:versions
npm.cmd run check:gitlab-oauth -- https://gitlab.example.com

표준 MCP 번들 경로는 distribution.json에 정의되어 있습니다. 현재 구성은 server/dist/gitlab-mcp.cjs를 빌드합니다. MCP 번들 자체는 생성물이며 소스 제어에서 제외되고 릴리스 아티팩트에 포함됩니다. 하네스 패키지는 하네스 측 런타임 종속성을 선언할 수 있습니다. 예를 들어 Pi 패키지는 MCP SDK를 사용하여 해당 번들 서버를 Pi에 브리지합니다.

distribution.json은 공유 배포 메타데이터의 권위 있는 소스입니다. 여기에는 중립적인 gitlab 배포 식별자, 기본 버전, 설명, 라이선스, 표준 MCP 번들 및 Skills 경로가 포함됩니다. 변경 후 npm run adapters:generate를 실행하고 생성된 Codex/Claude Code/Cline/Pi 메타데이터를 검토하십시오. npm run adapters:check는 메타데이터 드리프트와 누락되었거나 디렉터리가 아니거나 저장소를 벗어나는 표준 Skills 경로를 거부합니다.

npm run check:bundle은 인메모리 클린 빌드를 수행하며 표준 번들에 하네스별 구현 참조가 포함되면 실패합니다. npm run check:versions는 생성된 패키지 및 Codex 릴리스 메타데이터가 distribution.json과 일치하는지 검증합니다. Codex 플러그인 매니페스트는 기본 배포 버전을 변경하지 않고 + 뒤에 Codex 빌드 메타데이터를 추가할 수 있습니다. SERVER_VERSION은 하네스 중립적인 MCP 코어가 독립적으로 소유하며 코어 런타임 자체가 변경될 때만 증가합니다.

하네스 중립적인 코어와 어댑터 경계는 ADR-001에 문서화되어 있습니다. GEN-08 집중 감사 및 식별 결정은 docs/GENERALISATION_AUDIT.md에 기록되어 있습니다.

지속적 통합

GitLab 머지 리퀘스트, 기본 브랜치 및 태그 파이프라인은 구문 검사, 테스트, 커버리지, dependency-cruiser, 포맷팅/린팅, 프로덕션 종속성 감사, 클린 번들 빌드 및 번들된 stdio/HTTP 스모크 테스트를 실행합니다. GitLab SAST 및 시크릿 탐지 템플릿도 활성화됩니다. Codex, Claude Code, Cline, Pi 각각은 표준 빌드 후 집중 어댑터 검증을 수행합니다. 해당 작업은 하네스 패키징과 MCP 시작을 검증하며, 코어 Node/보안 매트릭스를 반복하지 않습니다.

태그 파이프라인은 결정적 Codex 아카이브를 CycloneDX SBOM 및 SHA256SUMS와 함께 게시하고, 일치하는 .sha256 사이드카가 있는 재현 가능한 Claude Code, Cline, Pi MCP + Skills 아카이브도 게시합니다. 최종 릴리스 세트 게이트는 정확히 네 가지 지원 하네스를 요구하며 표준 MCP 번들과 Skills 다이제스트를 비교합니다. 릴리스는 docs/PUBLICATION_CHECKLIST.md에 따라 아티팩트가 검증될 때까지 완료된 것으로 간주되지 않습니다.

커밋된 docs/gitlab-tool-contracts.json 인벤토리는 경계 유효 입력으로 모든 등록된 도구를 호출하고 안전 분류, HTTP 메서드, 인코딩된 경로, 쿼리/본문 매핑 및 제한된 응답 모드를 고정합니다. 커버리지는 모든 프로덕션 소스 모듈을 포함하며 90% 라인, 80% 함수 또는 75% 브랜치 미만이면 실패합니다. 인벤토리 항목 없이 도구를 추가하면 테스트가 실패합니다.

구문 검사 및 테스트 작업은 node:22-alpine과 node:24-alpine 모두에서 실행됩니다. 임계값이 적용된 커버리지 작업은 Node 22에서 실행됩니다. 코어 작업은 이러한 이미지를 실행하고 npm 레지스트리에 도달할 수 있는 태그 없는 Linux 러너가 필요합니다. 보안 템플릿은 GitLab 레지스트리에서 분석기 이미지를 가져옵니다. 코어 Node.js 작업에는 권한 모드가 필요하지 않습니다. 태그 없는 작업을 수락하고 병합을 위한 성공적인 파이프라인을 요구하기 전에 작업이 최소 10분 동안 실행되도록 허용하는 프로젝트, 그룹 또는 인스턴스 러너를 하나 이상 구성하십시오.

로컬 Codex 인증

Codex를 실행하는 환경에서 인스턴스 URL과 토큰을 설정하십시오:

$env:GITLAB_URL = "https://gitlab.example.com"
$env:GITLAB_TOKEN = "<token>"

GITLAB_URL은 기본적으로 HTTPS를 사용해야 하며 포함된 자격 증명, 쿼리 및 프래그먼트를 거부합니다. TLS를 사용할 수 없는 명시적 로컬/프라이빗 개발 GitLab 인스턴스의 경우 GITLAB_ALLOW_INSECURE_HTTP=true를 설정하십시오. 이 재정의는 프로덕션 및 공개 호스트 이름에서 거부됩니다. 루프백, 프라이빗 네트워크 IP, 단일 레이블 호스트 및 .localhost, .local, .internal, .home.arpa 프라이빗 개발 접미사를 허용합니다.

GITLAB_URL은 기본적으로 https://gitlab.com입니다. Codex .mcp.json은 stdio를 통해 번들 서버를 시작하고 하네스 중립적인 코어 앞에 경량 Codex 배포 어댑터를 로드합니다. 토큰은 런타임에 읽히며 배포판에 저장되지 않습니다.

작업을 포괄하는 가장 좁은 토큰 범위를 사용하십시오. 읽기 전용 작업은 읽기 지향 토큰을 사용할 수 있습니다. 저장소, 이슈, 머지 리퀘스트 또는 CI 변경에는 해당 GitLab API 권한이 필요합니다.

기능 탐지

GitLab 작업이 지원되지 않는지, 라이선스가 없는지, 비활성화되었는지 아니면 현재 자격 증명으로 단순히 접근할 수 없는지 진단하기 전에 get_gitlab_capabilities를 호출하십시오. 이 함수는 /user, /version, /metadata, /personal_access_tokens/self 및 (자격 증명이 개인 액세스 토큰이 아닌 경우) /oauth/token/info에 대해서만 읽기 전용 요청을 사용합니다. OAuth 진단은 범위와 남은 수명을 보고하지만 토큰이나 OAuth 애플리케이션 식별자는 절대 노출하지 않습니다. GitLab은 특히 오래된 자체 관리 버전이나 비관리자에게 이러한 엔드포인트를 숨기거나 생략할 수 있으므로 모호한 결과는 추측하지 않고 unknown으로 보고됩니다.

각 기능은 available, unavailable, permission_required, license_required, not_configured 또는 unknown 중 하나이며 간결한 이유와 유용한 경우 지원 증거가 함께 제공됩니다. 정규화된 프로브별 결과를 보려면 detailed: true를, 캐시를 우회하려면 refresh: true를 전달하십시오.

결과는 정규화된 인스턴스 URL과 인증된 자격 증명 ID별로 60초 동안 캐시됩니다. 캐시 키에는 원시 베어러 토큰이 아닌 단방향 SHA-256 다이제스트가 포함됩니다. 항목은 60초 후 만료되며 refresh로 우회되고 인스턴스나 변경된 자격 증명을 자연스럽게 분리합니다. 만료된 항목은 기회적으로 제거되며 256개 항목 LRU 제한이 하드 메모리 경계를 제공합니다. 캐시는 인메모리 전용이며 MCP 서버 프로세스가 재시작되면 지워집니다.

HTTP 서버

로컬 개발용:

$env:MCP_PUBLIC_URL = "https://mcp.example.com/mcp"
$env:GITLAB_URL = "https://gitlab.example.com"
npm.cmd run start:http

HTTP 모드는 모든 /mcp 요청에 베어러 토큰을 요구합니다. 서버 측 토큰은 기본적으로 비활성화되어 있습니다. ALLOW_SERVER_TOKEN_HTTP=true는 통제된 프라이빗 테스트 전용으로 존재하며 공유 배포에 사용해서는 안 됩니다.

검사 전용 배포에는 MCP_READ_ONLY=true를 설정하십시오. 이 모드에서 서버는 읽기 전용으로 주석 처리된 도구만 등록하고 GitLab의 read_api OAuth 범위를 광고합니다. 기본 쓰기 가능 모드는 전체 도구 세트를 노출하며 api를 요구합니다. 서버는 등록 중에 모든 도구 주석을 검증하므로 분류되지 않았거나 변경을 수행하는 도구가 읽기 전용 표면에 조용히 진입할 수 없습니다.

IPv4 와일드카드 0.0.0.0 또는 IPv6 와일드카드 ::에 바인딩할 때는 MCP_ALLOWED_HOSTS를 공개 호스트 이름의 쉼표로 구분된 허용 목록으로 설정하세요. 서비스를 HTTPS 뒤에 두고 MCP_PUBLIC_URL을 정식 공개 /mcp URL로 설정하세요. 프로덕션 모드에서는 MCP_PUBLIC_URL이 필요하며, 포함된 자격 증명, 쿼리, 프래그먼트 및 /mcp 이외의 경로를 거부하고 HTTPS를 요구합니다. MCP_ALLOW_INSECURE_PUBLIC_URL=true는 루프백 리스너에서의 명시적인 로컬 개발에만 사용할 수 있으며 프로덕션 또는 공개 호스트에서는 거부됩니다. ALLOW_SERVER_TOKEN_HTTP=true도 마찬가지로 루프백 비공개 테스트로 제한되며 공유 배포에는 사용해서는 안 됩니다.

설치 또는 배포 후 읽기 전용 get_runtime_info 도구를 사용하여 코어/배포 버전, 배포 모드, 읽기 전용 필터링, 등록된 도구 인벤토리의 결정적 SHA-256 지문을 확인하세요.

HTTP MCP 요청 본문은 기본적으로 8MiB로 제한됩니다. 이는 제한된 다중 파일 커밋 및 기타 합법적인 대용량 도구 페이로드를 수용하면서 무제한 요청 버퍼링을 방지합니다. 다른 배포 제한을 사용하려면 MCP_MAX_REQUEST_BYTES를 65,536바이트에서 26,214,400바이트 사이의 정수로 설정하세요. 서버 앞에 있는 모든 리버스 프록시는 최소한 동일한 요청 크기를 허용해야 합니다.

장기 실행 HTTP 배포는 또한 인증 및 요청 상태를 제한합니다:

• MCP_TOKEN_CACHE_MAX_ENTRIES는 검증된 베어러 신원을 제한하며, 기본값 256, 60초 TTL 및 LRU 축출;

• MCP_AUTH_FAILURE_LIMIT는 MCP_AUTH_FAILURE_WINDOW_MS 내에서 직접 연결된 주소당 거부된 토큰을 제한하며, 기본값 60초당 20회 실패;

• MCP_AUTH_FAILURE_MAX_ENTRIES는 실패 추적 상태를 제한하며, 기본값 1,024;

• MCP_MAX_CONCURRENT_REQUESTS는 활성 MCP 요청을 제한하며, 기본값 32; 그리고

• MCP_MAX_CONCURRENT_REQUESTS_PER_IDENTITY는 검증된 GitLab 사용자 한 명당 요청을 제한하며, 기본값 4.

TLS 리버스 프록시에서 보완적인 속도 및 연결 제한을 구성하세요. 애플리케이션은 기본적으로 전달된 헤더를 신뢰하지 않고 직접 피어 주소를 의도적으로 사용하므로, 프록시 수준의 클라이언트 IP 제한은 트래픽이 이 서비스에 도달하기 전에 적용되어야 합니다.

인증되지 않은 /health 엔드포인트는 토폴로지가 없는 프로세스 활성 상태 확인입니다. /ready는 별도의 준비 상태 확인이며 종속성 프로브를 사용할 수 없을 때 503을 반환합니다. 모든 응답에는 생성된 X-Request-Id가 포함됩니다. 내부 MCP 실패는 해당 식별자와 오류 유형만 기록합니다. 임베더는 베어러 토큰이나 요청 페이로드를 받지 않고 메트릭용 요청 완료 관찰자를 제공할 수 있습니다.

배포 후 공개 리소스 메타데이터와 두 가지 상태 의미를 모두 검증하세요:

npm.cmd run check:mcp-deployment -- https://mcp.example.com/mcp

안전 모델

• 도구는 읽기 전용, 쓰기 및 파괴적 주석을 광고합니다.

• create_commit은 비파괴적 파일 작업만 지원합니다. 삭제 및 강제 커밋 업데이트는 동시성 안전 필드가 있는 별도로 주석이 달린 create_destructive_commit 도구가 필요합니다.

• GitLab 응답 본문(작업 로그, 아티팩트 및 API 오류 포함)은 엄격한 바이트 제한 하에 스트리밍되며 요청 시간 초과의 적용을 받습니다.

• API 오류는 자격 증명을 반향하지 않고 정규화됩니다.

• 기능 검색은 오류 증거를 편집하고 비공개 CI 변수 또는 변형 엔드포인트를 절대 읽지 않습니다.

• HTTP 베어러 토큰은 구성된 GitLab 인스턴스에 대해 검증되고 제한된 TTL/LRU 캐시에서 단방향 토큰 해시로 캐시됩니다.

• 거부된 자격 증명 및 동시 요청은 토큰이나 비공개 신원 세부 정보를 기록하지 않고 제한됩니다.

• HTTP 모드는 보호된 리소스 메타데이터로 인증되지 않은 요청에 도전합니다.

• HTTP 도구는 도구별 OAuth 또는 비공개 서버 토큰 보안 체계와 모델에 표시되는 재인증 도전을 광고합니다. 그리고

• 스킬은 병합, 승인, 삭제, 토론 해결 및 CI 상태 변경에 대한 명시적 의도를 요구합니다.

라이선스

MIT