GitLab MCP Server

AI 어시스턴트를 GitLab에 연결하여 머지 리퀘스트 검토, 파이프라인 문제 분류, 이슈 관리, 릴리스 초안 작성까지 일상 언어로 처리하게 하세요. 단일 정적 바이너리(또는 컨테이너)로 전체 REST + GraphQL API를 통해 1000개 이상의 GitLab 도구를 제공하며, Claude, Cursor, VS Code 및 모든 MCP 클라이언트에서 작동합니다.

여러분은 AI 어시스턴트와 대화하고, 어시스턴트가 GitLab 작업을 처리합니다. 기억해야 할 프로젝트 ID, API 엔드포인트, JSON이 없습니다.

"머지 리퀘스트 !15를 검토해 줘 — 병합해도 안전할까?" · "마지막 파이프라인은 왜 실패했지?" · "나에게 할당된 열린 이슈를 나열해 줘" · "v1.0에서 v2.0까지 릴리스 노트를 생성해 줘"

🤖 AI 어시스턴트를 사용 중인가요? 이 저장소 URL을 알려 주고 클라이언트에 서버를 설치해 달라고 요청하세요. 모델이 헤드리스로 처리하는 데 필요한 모든 것 — 클라이언트별 선언적 구성, claude mcp add 원라이너, 기본값 — 은 llms.txt에 있습니다(대화형 마법사 불필요).

60초 만에 설치

하나를 선택하세요. 어떤 경로든 마지막에는 어시스턴트에게 프롬프트를 입력하게 됩니다.

원클릭 설치

각 버튼은 Docker 기반 서버를 등록합니다(첫 실행 시 이미지를 자동으로 가져오며, Docker가 설치되어 있어야 합니다). Claude Desktop 행은 대신 네이티브 .mcpb 데스크톱 확장 프로그램을 다운로드합니다(macOS 유니버설 + Windows, Docker 불필요). Claude Desktop으로 열고 설정을 입력하세요. 토큰이 필요하신가요? api 범위의 개인 액세스 토큰 생성을 참조하세요. 자체 호스팅 GitLab을 사용하시나요? 설치 후 클라이언트의 MCP 구성에 GITLAB_URL 환경 변수를 추가하세요.

Claude Code(claude mcp add)로 설치

Docker(설치 불필요 — 첫 실행 시 이미지를 가져옴):

claude mcp add gitlab --env GITLAB_TOKEN=glpat-xxxx --transport stdio \
  -- docker run -i --rm -e GITLAB_TOKEN ghcr.io/jmrplens/gitlab-mcp-server:latest --http=false

또는 네이티브 바이너리를 먼저 설치한 다음 등록하세요:

# macOS/Linux (Homebrew)
brew install jmrplens/tap/gitlab-mcp-server
# Linux/macOS (script)
curl -fsSL https://raw.githubusercontent.com/jmrplens/gitlab-mcp-server/main/scripts/install.sh | sh
# Windows (winget)
winget install --id jmrplens.gitlab-mcp-server -e
# Windows (PowerShell)
irm https://raw.githubusercontent.com/jmrplens/gitlab-mcp-server/main/scripts/install.ps1 | iex

claude mcp add gitlab --env GITLAB_TOKEN=glpat-xxxx -- gitlab-mcp-server

자체 호스팅 GitLab인가요? --env GITLAB_URL=https://gitlab.example.com을 추가하세요(자체 서명 인증서의 경우 --env GITLAB_SKIP_TLS_VERIFY=true도 추가).

안내 설정(모든 클라이언트, 외울 플래그 없음)

이 바이너리에는 GitLab 토큰을 수집하고 MCP 클라이언트를 대신 구성해 주는 설정 마법사가 포함되어 있습니다. JSON을 직접 편집하고 싶지 않다면 이상적입니다:

gitlab-mcp-server --setup

VS Code, Claude Desktop, Claude Code, Cursor, Windsurf를 자동으로 감지하여 올바른 구성을 작성합니다. Windows에서는 .exe 파일을 더블클릭하여 실행하세요.

수동 JSON(Claude Desktop, Cursor, VS Code, …)

네이티브 바이너리(Claude Desktop mcpServers, Cursor 등):

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "env": { "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

VS Code(.vscode/mcp.json, servers + type 참고):

{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "/path/to/gitlab-mcp-server",
      "env": { "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

Docker 변형 — "command"/"args"를 다음으로 교체:

"command": "docker",
"args": ["run", "-i", "--rm", "-e", "GITLAB_TOKEN", "ghcr.io/jmrplens/gitlab-mcp-server:latest", "--http=false"]

Cline(VS Code) — Cline 사이드바 → MCP 서버 아이콘 → 전역 MCP 편집을 열거나 설정 파일을 직접 편집하세요:

• macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

• Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

• Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

Cline은 네이티브 바이너리에 대해 위에 표시된 mcpServers 형식을 사용합니다.

사용자별 stdio 대신 공유되는 장기 실행 HTTP 배포의 경우 HTTP 서버 모드를 참조하세요.

설치 없이 사용해 보기(호스팅 엔드포인트)

공개 인스턴스가 https://mcp.jmrp.io/gitlab 에서 실행됩니다. 설치할 것이 없고, 자신의 GitLab 토큰 외에 계정도 필요하지 않습니다. HTTP를 지원하는 MCP 클라이언트를 여기에 연결하세요:

{
  "mcpServers": {
    "gitlab": {
      "type": "http",
      "url": "https://mcp.jmrp.io/gitlab",
      "headers": { "PRIVATE-TOKEN": "glpat-xxxxxxxxxxxx" }
    }
  }
}

PRIVATE-TOKEN은 필수이며 요청마다 전송됩니다. 서버에 저장되지 않습니다. GITLAB-URL은 선택 사항이며 기본값은 https://gitlab.com입니다. 다른 인스턴스에 연결하려면 설정하세요(공개 인터넷에서 접근 가능해야 합니다).

서버를 사용해 보는 가장 빠른 방법이지만, 계속 사용하기에 올바른 방법은 여전히 로컬 실행(위의 어떤 옵션이든)입니다. 단순한 면책 조항이 아니라 구체적인 이유가 있습니다. 여러분의 토큰과 모든 요청이 다른 사람의 컴퓨터를 거쳐 갑니다. 로컬에서 실행하면 자격 증명과 GitLab 트래픽이 컴퓨터를 떠나지 않으므로, 비공개 자체 호스팅 인스턴스에서도 유일하게 합리적인 선택입니다.

이 엔드포인트는 기본 dynamic 표면에서 상태 비저장 스트리밍 HTTP입니다. POST가 전송 방식이며, GET은 설계상 405로 응답합니다. https://mcp.jmrp.io/gitlab/health는 {"status":"ok",…}와 함께 200으로 응답합니다. 자체 호스팅 HTTP 배포는 --auth-mode=oauth --gitlab-url=https://gitlab.com --public-url=https://mcp.example.com로 실행할 수도 있습니다(두 옵션 모두 필수입니다. OAuth는 고정된 인스턴스와 RFC 9728이 리소스를 식별하는 외부에서 접근 가능한 오리진이 필요합니다). 이 경우 클라이언트는 해당 메타데이터를 통해 GitLab을 인증 서버로 발견하고 토큰을 복사하는 대신 브라우저에서 인증을 수행합니다. OAuth 앱 설정을 참조하세요. 이 서버는 제가 유지 관리하는 MCP 서버 디렉터리인 mcp.jmrp.io 에 나열된 서버 중 하나이며, 각각 자체 엔드포인트로 접근할 수 있습니다. https://mcp.jmrp.io/servers.json은 자동화된 클라이언트를 위한 동일한 목록입니다.

그런 다음 그냥 물어보세요: AI 클라이언트를 열고 *"내 GitLab 프로젝트 목록을 보여줘."*라고 시도해 보세요. 클라이언트별 자세한 내용은 시작 가이드와 추가 예시 프롬프트를 참조하세요.

Related MCP server: GitLab MCP Server

왜 이 서버인가

• 자연어 기반 GitLab. AI가 "MR !15 병합해도 안전한가요?"를 적절한 API 호출로 변환합니다. 엔드포인트, ID, JSON을 직접 다룰 필요가 없습니다.

• 전체 플랫폼 — 1000+ 도구. 방대한 GitLab REST v4 + GraphQL 지원: 프로젝트, 브랜치, 태그, 릴리스, 머지 리퀘스트, 이슈, 파이프라인, 작업, 그룹, 사용자, 위키, 환경, 배포, 패키지, 컨테이너 레지스트리, 러너, 기능 플래그, CI/CD 변수, 보안, 관리, 토큰 등.

• 기본적으로 토큰을 적게 사용. 기본 dynamic 서피스는 전체 카탈로그에 접근하면서 단 2개의 도구(find + execute)만 노출하므로 모든 클라이언트의 컨텍스트 윈도우에 맞습니다. (토큰 사용량 →)

• 실제 모델로 입증됨. 자동 평가기가 라이브 GitLab 인스턴스를 대상으로 Anthropic, Google, OpenAI, Qwen을 실행합니다: 수천 건의 작업에 걸쳐 99.5% 종합 성공률. (결과 →)

• 안전한 설계. 읽기 전용 모드, 안전 모드(모든 뮤테이션의 dry-run 미리보기), 자체 호스팅 GitLab을 위한 TLS 옵션, 그리고 지속적인 SonarCloud 품질/보안 게이트.

• 어디서든 실행 가능. 단일 정적 바이너리 또는 컨테이너; Windows, Linux & macOS; amd64 & arm64; stdio(데스크톱) 및 HTTP(원격).

• 45개 MCP 리소스 (읽기 전용 데이터: 프로젝트, 이슈, 파이프라인, MR, 브랜치, 멤버, 서피스를 인식하는 gitlab://tools 매니페스트 및 워크플로 모범 사례 가이드). 26개의 단일 객체 종류도 구독 가능합니다.

• 37개 MCP 프롬프트 (코드 리뷰, 파이프라인 상태, 리스크 평가, 릴리스 노트, 스탠드업, 분석, 감사 등).

• 4개의 유도 마법사 (대화형 이슈/MR/릴리스/프로젝트 생성).

• 4개 MCP 기능 (completions, progress, elicitation, 리소스 구독 — 폴링으로 처리되는 실시간 resources/updated 알림) 및 MCP 클라이언트에서 시각적 식별을 위한 51개 도구 아이콘 (50개 도메인 아이콘 + 프로젝트 마크).

• 페이지네이션: 모든 목록 엔드포인트에서 전체 메타데이터와 함께 제공.

도구 서피스

서버는 TOOL_SURFACE로 제어되는 세 가지 형태로 GitLab을 제공할 수 있습니다. 기본값은 구성이 필요 없습니다.

도구 수는 GitLab 에디션(GITLAB_TIER)에 따라 달라집니다. 상위 티어일수록 더 많은 작업을 노출합니다. 순위 모델, 안전 장치 및 전체 카탈로그는 Dynamic Toolset 및 Meta-Tools Reference를 참조하세요. 리소스가 컨텍스트를 주로 차지하는 dynamic 실행의 경우 CAPABILITY_SURFACE=minimal로 설정하세요.

토큰 사용량

현재 카탈로그를 대상으로 go run ./cmd/audit_tokens/ -footprint로 측정했습니다. 합계는 MCP 클라이언트에 표시되는 시작 컨텍스트(표시되는 도구 스키마 + 공유 리소스 및 프롬프트)를 cl100k_base 토크나이저(GPT-4/GPT-3.5 인코딩)로 추정한 값입니다. 전체 매트릭스(meta 및 individual 서피스, 모든 META_PARAM_SCHEMA 모드)는 Token Footprint Reference를 참조하세요.

기본 구성: TOOL_SURFACE가 설정되지 않았거나 TOOL_SURFACE=dynamic이고, CAPABILITY_SURFACE=full, META_TOOLS 미설정, META_PARAM_SCHEMA=opaque, GITLAB_TIER 미설정(감지, 폴백 free)인 경우 서버는 dynamic find/execute 서피스를 사용합니다. TOOL_SURFACE=meta는 도메인 메타 도구를 명시적으로 원할 때만 사용하고, TOOL_SURFACE=individual은 클라이언트가 전체 도구 카탈로그를 처리할 수 있을 때만 사용하세요.

행은 티어 열에 다른 명시가 없으면 기본 Community Edition 카탈로그를 사용합니다. GITLAB_TIER는 사용 가능한 작업을 제어하며, 상위 티어일수록 더 많은 도구와 그에 따른 더 많은 접근 가능한 작업을 노출합니다.

호환성

다음 환경에서 테스트됨: VS Code + GitHub Copilot, Claude Desktop, Claude Code, Cursor, Windsurf, JetBrains IDEs, Zed, Kiro, Cline. 전체 Compatibility Matrix를 참조하세요.

AI 모델 도구 사용 평가

이 프로젝트에는 모델을 대상으로 한 MCP 품질 자동 평가기가 포함되어 있습니다. 도구 카탈로그에 대해 스키마 전용 검사를 실행하거나, Docker GitLab CE 또는 픽스처로 채워진 라이선스 Enterprise 인스턴스를 대상으로 MCP를 통해 검증된 모델 도구 호출을 실행합니다. Anthropic, Google, OpenAI, Qwen 전반에 걸쳐 각 모델이 올바른 작업을 선택하는지, 유효한 매개변수를 전송하는지, 조치 가능한 GitLab 오류에서 복구하는지, 파괴적 작업 보호 장치를 준수하는지 측정합니다.

현재 게시된 결과: Docker CE dynamic 20260627-232303.

게시된 모델 평가 세트는 596개의 작업 시도와 2220개의 예상 MCP 작업을 다룹니다. 선택된 보고서 전체에서 모델은 2265개의 모델 요청에 걸쳐 2265개의 도구 호출을 생성했으며, 종합 최종 성공률은 99.5%입니다. 자세한 현재 매트릭스는 AI Model Evaluation Results를 참조하세요.

현재 게시된 결과: Docker Enterprise meta 20260527.

문서

전체 문서는 **jmrp.io/docs/gitlab-mcp-server**에서 확인할 수 있습니다. 특정 영역에 대한 정확한 참조는 이 표를 사용하세요.

FAQ

네. GITLAB_URL을 인스턴스 URL로 설정하세요. GITLAB_URL을 생략하면 stdio 모드는 https://gitlab.com을 사용합니다. 자체 서명 TLS 인증서는 GITLAB_SKIP_TLS_VERIFY=true로 지원됩니다.

직접 실행하는 경우(stdio를 통한 로컬 또는 자체 인프라에서 HTTP를 통한) 모든 API 호출은 GitLab 인스턴스로 직접 전송됩니다. 다른 곳으로 나가는 유일한 요청은 GitHub Releases에 대한 업데이트 확인이며, 기본적으로 켜져 있고 AUTO_UPDATE=false로 비활성화할 수 있습니다.

예외는 호스팅 엔드포인트입니다. https://mcp.jmrp.io/gitlab을 사용한다는 것은 토큰과 모든 요청이 해당 머신을 통과한다는 뜻입니다. 거기에는 아무것도 저장되지 않지만, 다른 사람의 서버이므로 호스팅 섹션에서 계속 로컬로 사용하라고 안내하는 것입니다.

업데이트 확인이 정확히 무엇을 전송하는지는 PRIVACY.md를, 보안 모델은 SECURITY.md를 참조하세요.

네. GITLAB_READ_ONLY=true로 설정하면 모든 변경 도구(생성, 업데이트, 삭제)가 비활성화됩니다. 읽기 작업만 사용할 수 있습니다.

또는 GITLAB_SAFE_MODE=true로 설정하면 드라이런 모드가 됩니다. 변경 도구는 계속 표시되지만 실행하는 대신 구조화된 JSON 미리보기를 반환합니다. 감사, 교육, AI 어시스턴트가 수행할 작업을 검토하는 데 유용합니다.

Community Edition(CE)과 Enterprise Edition(EE)을 모두 지원합니다. stdio 모드에서 GITLAB_TIER=premium 또는 GITLAB_TIER=ultimate를 설정하면 Premium/Ultimate 기능(DORA 메트릭, 취약점, 컴플라이언스 등)을 위한 추가 도구가 활성화됩니다. 설정하지 않으면 인스턴스 라이선스에서 티어를 감지합니다(기본값 free). HTTP 모드에서는 --tier로 티어를 강제할 수 있으며, 그렇지 않으면 라이선스에서 토큰+URL 풀 항목별로 감지합니다.

서버에는 GitLab API 속도 제한에 대한 백오프가 포함된 재시도 로직이 있습니다. 오류는 일시적(재시도 가능) 또는 영구적으로 분류되며, 오류 메시지에 실행 가능한 힌트가 포함됩니다.

MCP 호환 클라이언트는 모두 지원됩니다: VS Code + GitHub Copilot, Claude Desktop, Cursor, Claude Code, Windsurf, JetBrains IDEs, Zed, Kiro 등. 내장된 설정 마법사는 대부분의 클라이언트를 자동 구성할 수 있습니다.

소스에서 빌드

git clone https://github.com/jmrplens/gitlab-mcp-server.git
cd gitlab-mcp-server
make build

게시된 컨테이너 이미지는 ghcr.io/jmrplens/gitlab-mcp-server:latest입니다. 크로스 컴파일, Docker Compose, 기여 지침은 개발 가이드를 참조하세요.

개인정보 보호정책

서버는 전적으로 사용자 머신에서 실행되며 자체 텔레메트리, 분석, 백엔드가 없습니다 — 데이터는 사용자가 구성한 MCP 클라이언트와 GitLab 인스턴스 사이에서만 흐릅니다(GitHub Releases에 대한 선택적 서명 바이너리 업데이트 확인 제외). 토큰은 GitLab 요청 인증에만 사용되며 절대 기록되지 않습니다. 자세한 내용: PRIVACY.md.

기여 및 보안

• 기여: 개발 지침, 브랜치 명명 규칙, 커밋 규칙, PR 프로세스는 CONTRIBUTING.md를 참조하세요.

• 보안: 보안 정책과 취약점 신고는 SECURITY.md를 참조하세요.

• 행동 강령: CODE_OF_CONDUCT.md를 참조하세요(Contributor Covenant v2.1).

저장소 미러: GitHub가 공식 저장소입니다. 검색 가능성을 위해 GitLab.com에 읽기 전용 미러가 제공되며, 기여는 GitHub에서 해 주세요.

파일 수

함수

주목할 만한 비율

코드 패턴

프로젝트

명예의 전당

그냥 궁금해서