고급 GitLab MCP 서버

고급 GitLab MCP 서버 — CQRS 아키텍처, OAuth 2.1 및 다중 전송 모드를 갖춘 18개 엔티티 유형에 걸친 44개의 도구.

빠른 시작

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@structured-world/gitlab-mcp"],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "https://gitlab.com"
      }
    }
  }
}

요구 사항: Node.js >= 24

Related MCP server: GitLab MCP Server

주요 특징

• 44개의 도구 (18개 엔티티 유형): 프로젝트, 머지 리퀘스트, 파이프라인, 작업 항목, 위키 등

• CQRS 아키텍처 — 쿼리용 browse_*, 명령용 manage_*

• 연결 복원력 — 제한된 시작 시간, 지수 백오프를 통한 자동 재연결, GitLab에 연결할 수 없을 때의 연결 해제 모드

• 다중 인스턴스 지원 — 인스턴스별 OAuth 및 속도 제한을 사용하여 여러 GitLab 인스턴스에 연결

• 다중 전송 방식 — stdio, SSE, StreamableHTTP

• OAuth 2.1 — Claude 커스텀 커넥터를 통한 사용자별 인증

• 읽기 전용 모드 — 프로덕션 환경을 위한 안전한 운영

• 자동 검색 — git 리모트에서 GitLab 설정 감지

• 세밀한 제어 — 도구 그룹 활성화/비활성화, 작업 필터링, 설명 사용자 지정

• Docker 지원 — ghcr.io/structured-world/gitlab-mcp:latest

문서

전체 문서는 **gitlab-mcp.sw.foundation**에서 확인할 수 있습니다.

자동 생성된 도구 참조

매개변수를 포함한 전체 도구 참조는 다음과 같습니다:

# View locally
yarn list-tools --detail

# Generate documentation
yarn list-tools --export --toc > docs/tools/api-reference.md

자동 생성된 도구 문서는 전체 API 참조를 확인하세요.

Docker

# HTTP mode
docker run -e PORT=3002 -e GITLAB_TOKEN=your_token -p 3333:3002 \
  ghcr.io/structured-world/gitlab-mcp:latest

# stdio mode
docker run -i --rm -e GITLAB_TOKEN=your_token \
  ghcr.io/structured-world/gitlab-mcp:latest

연결 복원력

서버는 GitLab 연결 문제를 다음과 같이 원활하게 처리합니다:

• 제한된 시작 시간 — GitLab 가용성과 관계없이 GITLAB_INIT_TIMEOUT_MS(기본값 5초) 내에 서버가 시작됩니다.

• 연결 해제 모드 — GitLab에 연결할 수 없는 경우(disconnected/failed 상태), 진단을 위한 whoami, switch_profile, set_scope와 같은 로컬 작업이 포함된 manage_context 도구만 노출됩니다. 활성 재연결(connecting 상태) 중에는 전체 도구 목록을 계속 사용할 수 있으므로 MCP 클라이언트가 일시적인 중단 중에 도구 카탈로그를 잃지 않습니다. MCP 클라이언트는 tools/list_changed를 통해 도구 가용성 변경 사항을 알림받습니다.

• 자동 재연결 — ±10% 지터를 포함한 지수 백오프 재연결(5초 → 60초).

• 오류 분류 — 일시적인 오류(네트워크, 5xx, 타임아웃)는 자동 재연결을 트리거합니다. 시작 시 인증/구성 오류는 failed 상태로 전환됩니다(자동 재연결 없음). 세션 중간의 토큰 취소는 주기적인 상태 확인과 함께 실행되는 인증된 HEAD /api/v4/user 확인을 통해 감지됩니다(정적 토큰 모드 전용; OAuth 모드에서는 건너뜀). 이 확인에서 401 또는 403 오류가 발생하면 인스턴스가 즉시 failed 상태로 전환됩니다.

• 인스턴스 상태 모니터 — 각 모니터링되는 인스턴스 URL은 자체 XState 상태 머신을 가집니다. 추적되지 않는 OAuth URL은 현재 연결 가능한 것으로 간주됩니다.

기능 플래그

기여

개발 설정, 테스트 및 PR 가이드라인은 CONTRIBUTING.md를 참조하세요.

프로젝트 후원

USDT (TRC-20): TFDsezHa1cBkoeZT5q2T49Wp66K8t2DmdA

라이선스

Apache License 2.0 — 자세한 내용은 LICENSE를 참조하세요.

zereight/gitlab-mcp (MIT) 기반. LICENSE.MIT 참조.