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초 캐시 + 쓰기 시 무효화

요구 사항

• 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 을 안내한다.

1. 안내된 URL 로 GitLab 에서 Personal Access Token 발급 (scope: api, read_repository, write_repository)
2. 로컬 콜백 페이지(http://localhost:17432)에 토큰을 붙여넣고 제출
3. 서버가 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 인스턴스에만 적용된다