zereight/gitlab-mcp
First gitlab mcp for you, building together
GitLab MCP 서버란?
gitlab-mcp는 AI 에이전트(Claude, Codex, Cursor, VS Code, Copilot 등)가 GitLab 인스턴스와 통신할 수 있게 하는 독립형 Model-Context-Protocol(MCP) 서버입니다. GitLab REST/GraphQL API를 MCP 인터페이스 뒤에 래핑하여 LLM이 직접 호출할 수 있는 수백 개의 즉시 사용 가능한 도구(예: create-merge-request, list-issues, run-pipeline, read-wiki)를 노출합니다.
존재 이유
- 공식 GitLab MCP 서버는 GitLab에 내장되어 있으며 상대적으로 무겁습니다.
gitlab-mcp는 가볍고 한 번 설치하면 되는 바이너리로, 로컬, 컨테이너 또는 사용자 지정 자체 호스팅 GitLab에서 실행할 수 있습니다. - AI 에이전트 워크플로에 최적화되어 있습니다 – 도구는 도구 세트로 그룹화되고, 2단계 MR diff 검토, JMESPath 결과 필터링, 세분화된 권한 모드를 지원합니다.
- stdio, Server-Sent Events(SSE) 또는 스트리밍 가능한 HTTP를 통해 많은 MCP 클라이언트(Claude Code, Codex, Cursor, VS Code, Copilot, JSON 기반 클라이언트)와 작동합니다.
주요 기능(README에 설명된 대로)
| 기능 | 의미 |
|---|---|
275개 도구(도구 세트에 273개 + execute_graphql + discover_tools) |
큰 도구 상자; 최소한의 핵심 세트로 시작하고 런타임에 더 활성화할 수 있습니다. |
| 2단계 MR 검토 | 먼저 변경된 파일을 나열한 다음 diff를 배치로 가져옵니다 – 에이전트가 코드 변경을 추론하는 방식과 일치하는 패턴입니다. |
| 에이전트 스킬 내장 | 사전 작성된 "스킬"(프롬프트 스타일 지침)이 skills/gitlab-mcp/ 아래에 있어 에이전트가 도구를 올바르게 사용하는 데 도움이 됩니다. |
| 유연한 인증 | 개인 액세스 토큰(PAT), 로컬 OAuth2 브라우저 흐름, MCP 프록시 OAuth 또는 다중 사용자 배포를 위한 요청별 원격 인증. |
| 여러 전송 방식 | 로컬 클라이언트용 stdio, 레거시 클라이언트용 SSE, 원격 배포용 스트리밍 가능한 HTTP. |
| 클라이언트 친화적 설정 | Claude Code, Codex, Cursor, VS Code, Copilot 및 일반 JSON 기반 MCP 클라이언트용 기성 설치 명령. |
| 자체 호스팅 준비 | 사용자 지정 GitLab URL, 프록시 설정에서 작동하며 Docker, Homebrew, npm 또는 Nix에서 실행할 수 있습니다. |
| JMESPath 필터링 | 기본 GitLab 요청을 변경하지 않고 페이로드를 줄이기 위한 도구 JSON 결과의 선택적 후처리. |
| 권한 모드 | readonly, modify(파괴적 삭제 없음) 또는 full – 도구 및 도구 세트별로 적용됩니다. |
| 결과 압축 | 과도한 도구 응답을 미리 보기와 함께 잘라내고 전체 데이터를 가져오는 CLI 명령을 제공합니다. |
| 마스킹 지원 | 개인 정보에 민감한 필드에 대한 텍스트 응답 마스킹. |
실행 방법
- 설치 – npm(
npm i -g @zereight/mcp-gitlab), Homebrew(brew tap zereight/gitlab-mcp && brew install zereight-mcp-gitlab) 또는 Nix(flake를 입력으로 추가)를 통해. - 토큰 제공 –
GITLAB_PERSONAL_ACCESS_TOKEN(또는_FILE변형)을 설정하거나zereight-mcp-gitlab auth로 내장 OAuth 장치 흐름을 실행합니다. - 서버 시작 –
zereight-mcp-gitlab을 실행하기만 하면 됩니다. 기본적으로0.0.0.0:3002에서 수신 대기합니다. - MCP 클라이언트 구성 – 예: Claude Code의 경우:
VS Code, Cursor, Copilot 및 일반 JSON 기반 클라이언트에도 유사한 스니펫이 있습니다.claude mcp add gitlab \ --transport stdio \ --scope local \ --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" \ --env GITLAB_API_URL=https://gitlab.com/api/v4 \ -- zereight-mcp-gitlab
언제 사용하나요?
- AI 증강 개발 – LLM이 사용자 지정 API 호출 없이 브랜치 생성, 병합 요청 열기, CI 실행 또는 이슈 데이터 가져오기를 수행하게 합니다.
- 다중 사용자 AI 어시스턴트 – 원격 인증 모드를 사용하면 각 사용자가 자신의 PAT를 제시할 수 있어 개별 권한을 존중하는 공유 서버가 가능합니다.
- 자체 호스팅 GitLab – 서버는 모든 GitLab 인스턴스(
GITLAB_API_URL)를 가리킬 수 있어 내부 엔터프라이즈에 적합합니다. - 실험 – 도구 세트는 확장 가능(
discover_tools)하므로 서버 코드를 수정하지 않고 새 GitLab 관련 작업을 프로토타입할 수 있습니다.
가장 유용한 CLI 플래그 빠른 참조
| 플래그 | 용도 |
|---|---|
--token <PAT> |
개인 액세스 토큰에 대한 환경 변수를 재정의합니다. |
--api-url <URL> |
서버를 사용자 지정 GitLab API 엔드포인트로 지정합니다. |
| `--permission-mode <readonly | modify |
--toolsets <list> |
명명된 도구 그룹을 활성화합니다(예: core,wiki,milestones). |
--tools <tool1,tool2> |
기본 세트 위에 개별 도구를 추가합니다. |
--use-wiki, --use-milestone, --use-pipeline |
해당 도구 세트를 활성화하는 레거시 플래그(더 이상 사용되지 않음). |
--compact-results |
큰 도구 응답을 잘라내고 전체 페이로드를 가져오는 CLI 명령을 제공합니다. |
--masking-enabled |
개인 정보에 민감한 필드에 대한 응답 마스킹을 켭니다. |
자세히 알아보기
- 문서 사이트 – https://zereight.github.io/gitlab-mcp/ (전체 가이드, 도구 참조, 인증 세부 정보).
- 비교 차트 – 이 서버가 커뮤니티 스타일 GitLab MCP A 및 공식 GitLab MCP 서버와 어떻게 다른지 보여줍니다.
- 스킬 파일 –
skills/gitlab-mcp/에는 LLM이 도구를 올바르게 사용하는 데 도움이 되는 프롬프트 스니펫이 포함되어 있습니다.
TL;DR
gitlab-mcp는 GitLab을 AI 에이전트를 위한 풍부한 도구 상자로 바꾸는 특수 목적의 MCP 서버입니다. 바이너리를 설치하고, 토큰을 제공하고, 시작하고, LLM 기반 클라이언트를 가리키기만 하면 간단하고 권한을 인식하는 API를 통해 수백 개의 GitLab 작업(이슈, MR diff, 파이프라인, 위키, 릴리스 등)을 즉시 사용할 수 있습니다.
관련
- 프로젝트
- 프로젝트
- 프로젝트
- 프로젝트
- 프로젝트