Which integrations are available for this server?

Provides tools for interacting with GitLab's REST API v4, enabling AI agents to manage projects, issues, merge requests, pipelines, branches, wikis, and perform code reviews and comparisons on a GitLab instance.

How do I use gitlab-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@gitlab-mcp review my latest merge request" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

gitlab-mcp

by wisesky0

Overview Schema Related Servers Score Discussions

TypeScript

Local

GitLab MCP Proxy

사내 폐쇄망 GitLab 16.11 을 Claude Code 에서 MCP 로 사용하기 위한 프록시 서버 버전 0.4.0 · 연관 문서: docs/PRD.md, docs/test-design.md

GitLab REST API v4 를 MCP(Model Context Protocol) tool 로 래핑한다. Claude Code 에서 자연어로 MR 리뷰·이슈 확인·파이프라인 조회·브랜치 비교를 수행할 수 있다.

주요 특징

분할 MCP 프로필 — 같은 바이너리를 --profile 로 기동해 세션 목적별 tool 만 노출 (Token Budget 절감)
레지스트리 기반 확장 — TypeScript ToolGroup + YAML Spec 을 한 레지스트리로 통합, 코드 수정 없이 API 추가
OS 독립 토큰 저장 — Node 내장 crypto(AES-256-GCM) 암호화 파일. 외부 의존성/네이티브 모듈 없음
폐쇄망 대응 — 인스턴스별 SSL 검증 비활성, 다중 인스턴스 라우팅
응답 최적화 — 요약 필드 추출, 대용량 diff 파일 단위 분할, 민감 정보 자동 마스킹, 60초 캐시 + 쓰기 시 무효화

Related MCP server: GitLab MCP Server

요구 사항

Node.js 20 LTS 이상
TypeScript 5+

설치 및 빌드

npm install
npm run build        # tsc 컴파일 + src/specs/*.yaml → dist/specs 복사

설정

`config/instances.yaml` — GitLab 인스턴스

instances:
  - name: company-gitlab
    url: https://gitlab.internal.company.com
    default: true            # instance 미지정 시 이 인스턴스로 라우팅
    api_version: v4
    ssl_verify: false        # 폐쇄망 자체서명 인증서 대응

`config/config.yaml` — Tool Group 활성화

tool_groups:
  group:    { enabled: true }
  project:  { enabled: true }
  issue:    { enabled: true }
  mr:       { enabled: true }
  compare:  { enabled: true }
  pipeline: { enabled: false }   # 비활성 → tool 목록에서 제외 (Token Budget)
  repo:     { enabled: false }
  wiki:     { enabled: false }   # YAML 독립 등록 그룹
cache_ttl_seconds: 60
callback_port: 17432

Claude Code 연동

Step 1 — `config/instances.yaml` 에 GitLab 인스턴스 등록

instances:
  - name: company-gitlab
    url: http://localhost:8929   # 로컬 Docker 검증 시. 실서버는 사내 URL로 변경
    default: true
    api_version: v4
    ssl_verify: false

Step 2 — `config/config.yaml` 에서 사용할 Tool Group 활성화

tool_groups:
  group:    { enabled: true }
  project:  { enabled: true }
  issue:    { enabled: true }
  mr:       { enabled: true }
  compare:  { enabled: true }
  pipeline: { enabled: true }
  repo:     { enabled: true }
  wiki:     { enabled: true }
cache_ttl_seconds: 60
callback_port: 17432

필요 없는 그룹은 enabled: false 로 끄면 Claude 의 tool 목록에서 제외되어 Token Budget 을 절감한다.

Step 3 — 빌드

npm install
npm run build

Step 4 — Claude Code 에 MCP 서버 등록

claude mcp add 명령으로 등록한다. dist/index.js 와 config/ 는 절대 경로로 지정해야 Claude 가 어느 디렉토리에서 실행되든 올바르게 찾는다.

macOS / Linux

claude mcp add --scope user gitlab \
  -- node /Users/your-name/projects/gitlab-mcp/dist/index.js \
  --profile all \
  --config-dir /Users/your-name/projects/gitlab-mcp/config

Windows (PowerShell)

claude mcp add --scope user gitlab `
  -- node C:\Users\your-name\projects\gitlab-mcp\dist\index.js `
  --profile all `
  --config-dir C:\Users\your-name\projects\gitlab-mcp\config

--scope user — ~/.claude.json 에 저장되어 모든 프로젝트에서 전역으로 사용된다
--profile all — 8개 그룹 전체 활성화 (config.yaml 설정 무시)
--config-dir — instances.yaml 위치를 절대 경로로 지정

claude mcp list   # 등록 목록 + 연결 상태 확인

프로필 요약

프로필	노출 그룹	용도
`all`	전체 8개 그룹	기본 권장
`project`	group, project, issue, repo	프로젝트 탐색 + 코드
`mr`	mr, compare	코드 리뷰 전용
`pipeline`	pipeline	CI 모니터링 전용
(생략)	`config.yaml` 설정 그대로	커스텀

Token Budget 을 줄이려면 프로필별로 분리 등록한다:

# macOS / Linux
claude mcp add --scope user gitlab-mr \
  -- node /Users/your-name/projects/gitlab-mcp/dist/index.js \
  --profile mr \
  --config-dir /Users/your-name/projects/gitlab-mcp/config

claude mcp add --scope user gitlab-pipeline \
  -- node /Users/your-name/projects/gitlab-mcp/dist/index.js \
  --profile pipeline \
  --config-dir /Users/your-name/projects/gitlab-mcp/config

--profile 을 생략하면 config/config.yaml 의 tool_groups 설정을 그대로 따르므로, 아래처럼 모두 켜두고 등록해도 동일한 효과를 낸다.

claude mcp add gitlab -- node /Users/your-name/projects/gitlab-mcp/dist/index.js

방법	`config.yaml` 참조	wiki 포함 여부
`--profile all`	무시	항상 포함
`--profile` 생략	참조	설정값에 따라

인증 (토큰 등록)

토큰이 없으면 tool 호출 시 PAT 발행 페이지 URL 을 안내한다.

안내된 URL 로 GitLab 에서 Personal Access Token 발급 (scope: api, read_repository, write_repository)
로컬 콜백 페이지(http://localhost:17432)에 토큰을 붙여넣고 제출
서버가 GET /user 로 토큰을 검증 후 암호화 저장하고 콜백 서버를 즉시 종료

토큰 저장 방식 (OS 독립)

위치: ~/.gitlab-mcp/credentials.enc
암호화: AES-256-GCM. 키는 머신 고유값(hostname + 사용자명)에서 scrypt 로 파생
인스턴스별 분리 저장. 동일 머신/사용자에서만 복호화 가능
초기화: ~/.gitlab-mcp/credentials.enc 파일을 삭제하면 전체 재등록 상태로 돌아간다

폐쇄망에서 콜백 접근이 막히는 경우(V-05), tool 인자로 토큰을 직접 전달하는 폴백 경로를 사용한다.

YAML Spec 으로 API 추가 (코드 수정 없이)

src/specs/*.yaml 에 spec 을 추가하면 빌드 시 자동 등록된다.

# group 이 기존 TS ToolGroup 과 일치하면 병합, 없으면 독립 그룹으로 등록
group: wiki
description: GitLab Wiki 관리
tools:
  - name: list_wiki_pages
    description: Wiki 페이지 목록 조회
    method: GET
    path: /projects/{project_id}/wikis
    params:
      - { name: project_id, in: path, required: true }
      - { name: with_content, in: query, default: false, type: boolean }

독립 그룹은 기본 비활성이므로 config.yaml 에서 wiki: { enabled: true } 로 켜야 노출된다.

OpenAPI → YAML 변환 보조 CLI

npm run spec -- spec extract --source specs/gitlab-v4.yaml --tag wikis --output src/specs/wiki.yaml

테스트

npm test              # 전체 (Unit + Integration + Contract)
npm run test:cov      # 커버리지 (전체 80%+ 게이트)

Unit: 마스킹, 캐시, 토큰 저장, 설정/프로필, 레지스트리, 콜백 서버, 에러 매핑
Integration: GitLab 클라이언트 ↔ Mock, 도메인 tool, 인증 흐름, YAML generic handler
Contract: 실제 MCP Client ↔ Server (InMemoryTransport) tools/list·call 계약

Mock GitLab 은 fetch 주입 방식(tests/mock/mock-gitlab.ts)으로 결정적·고속이다.

Docker GitLab 16.11 CE (E2E 선검증)

사내 이관 전 로컬에서 실 GitLab API 계약을 검증한다. CE 전용이므로 EE 기능(MR 승인)은 사내 검증 대상이다.

docker compose -f tests/docker/docker-compose.yml up -d
docker compose -f tests/docker/docker-compose.yml ps      # healthy 대기 (부팅 5~10분+)
docker exec gitlab-test cat /etc/gitlab/initial_root_password

디렉토리 구조

src/
  index.ts            진입점 (--profile, stdio)
  server.ts           MCP 서버 조립 (tools/list·call)
  types/              ToolGroup, 설정, spec, GitLab 응답 타입
  config/             설정 로더 + 프로필
  auth/               토큰 저장(crypto), 콜백 서버, PAT URL, AuthService
  client/             GitLab REST 클라이언트, ClientManager
  registry/           ToolRegistry(병합/독립등록), spec→tool 변환
  tools/              도메인 ToolGroup (group/project/issue/mr/compare/pipeline/repo)
  specs/              YAML Spec (mr-extra, wiki)
  util/               마스킹, 캐시, 에러, 응답
config/               instances.yaml, config.yaml
tests/                unit / integration / contract / mock / fixtures / docker

보안 주의

토큰은 암호화 저장되며 *.enc 는 .gitignore 에 포함된다. 절대 커밋하지 않는다
API 응답의 private_token, runners_token, *_secret, webhook url token 등은 자동 마스킹된다
폐쇄망 SSL 비활성은 ssl_verify: false 인스턴스에만 적용된다

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/wisesky0/gitlab-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server