728x90
반응형
GitLab MCP 연동 가이드
작성일: 2026-06-08
작성자: tester1
대상 인스턴스: http://10.0.0.1:9820
목차
1. MCP란?
MCP(Model Context Protocol) 는 Anthropic이 2024년에 발표한 오픈 표준으로,
AI 모델(Claude 등)과 외부 도구/데이터 소스를 연결하는 프로토콜입니다.
Claude (MCP Client)
↕ MCP Protocol
GitLab MCP Server
↕ REST API
GitLab Instance (10.0.0.1:9820)MCP를 통해 Claude가 GitLab의 프로젝트, 이슈, MR, 파이프라인 등을 직접 조회하고 조작할 수 있습니다.
2. 사전 준비
2.1 Node.js 설치 확인
node -v # v18.0.0 이상 필요
npm -v # v9.0.0 이상 필요2.2 GitLab Personal Access Token 발급
- GitLab 접속:
http://10.0.0.1:9820 - 우측 상단 프로필 아이콘 클릭 → Edit Profile
- 좌측 메뉴 → Access Tokens
- Add new token 클릭
- 아래 항목 설정:
| 항목 | 값 |
|---|---|
| Token name | mcp-claude (임의 지정) |
| Expiration date | 원하는 만료일 설정 |
| Scopes | ✅ api 반드시 체크 |
- Create personal access token 클릭 후 토큰 값 복사 (재확인 불가)
3. 패키지 설치 및 설정
권장 패키지: @zereight/mcp-gitlab
# 전역 설치 (선택사항)
npm install -g @zereight/mcp-gitlab
# 또는 npx로 바로 실행 (설치 불필요)
npx @zereight/mcp-gitlab4. Claude Desktop 설정
4.1 설정 파일 위치
| OS | 경로 |
|---|---|
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
4.2 설정 파일 내용
{
"mcpServers": {
"gitlab": {
"command": "npx",
"args": [
"-y",
"@zereight/mcp-gitlab"
],
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "your_token_here",
"GITLAB_API_URL": "http://10.0.0.1:9820/api/v4"
}
}
}
}
⚠️
your_token_here부분을 2단계에서 발급한 실제 토큰으로 교체하세요.
4.3 Claude Desktop 재시작
설정 파일 저장 후 Claude Desktop을 완전히 종료하고 재시작합니다.
5. 연동 테스트
Claude Desktop 또는 Claude.ai에서 아래 명령어로 연동 상태를 확인합니다.
기본 연결 확인
내 GitLab 프로필 정보 보여줘정상 응답 예시:
사용자명: tester1
이메일: tester1@example.com
상태: active
관리자: true프로젝트 목록 조회
GitLab에서 내 프로젝트 목록 보여줘이슈 조회
test-prj 프로젝트의 열린 이슈 목록 보여줘6. 주요 사용 예시
📁 프로젝트 관리
# 프로젝트 목록
GitLab 프로젝트 목록 보여줘
# 특정 프로젝트 상세 정보
test-prj 프로젝트 정보 알려줘
# 파일 목록
test-prj 프로젝트의 파일 구조 보여줘🐛 이슈 관리
# 이슈 목록 조회
test-prj의 이슈 목록 보여줘
# 이슈 생성
test-prj에 이슈 만들어줘: 제목은 "버그 수정", 내용은 "로그인 오류 수정 필요"
# 이슈 상세 조회
test-prj의 이슈 #1 내용 보여줘🔀 Merge Request 관리
# MR 목록
test-prj의 열린 MR 목록 보여줘
# MR 상세
test-prj의 MR #1 내용과 변경사항 보여줘🚀 CI/CD 파이프라인
# 파이프라인 목록
test-prj의 최근 파이프라인 상태 보여줘
# 특정 파이프라인 잡 조회
test-prj 파이프라인 #5의 잡 목록 보여줘📝 파일 조작
# 파일 내용 조회
test-prj의 README.md 내용 보여줘
# 파일 생성/수정
test-prj에 docs/guide.md 파일 만들어줘7. 트러블슈팅
❌ 패키지를 찾을 수 없음 (404 오류)
npm error 404 Not Found - @gitlabhq/gitlab-mcp-server원인: 패키지명이 잘못됨
해결: @zereight/mcp-gitlab 또는 @yoda-digital/mcp-gitlab-server 사용
❌ 인증 오류 (401 Unauthorized)
원인: Personal Access Token이 잘못되었거나 만료됨
해결:
- GitLab에서 새 토큰 재발급
api스코프 체크 여부 확인claude_desktop_config.json의 토큰 값 업데이트 후 재시작
❌ 서버에 연결할 수 없음
원인: GitLab 인스턴스 URL이 잘못됨
해결: GITLAB_API_URL 값이 http://10.0.0.1:9820/api/v4 형식인지 확인
❌ MCP 서버가 목록에 보이지 않음
해결:
claude_desktop_config.jsonJSON 문법 오류 확인 (콤마, 따옴표 등)- Claude Desktop 완전 종료 후 재시작
- 로그 확인:
%APPDATA%\Claude\logs\
참고 링크
*
728x90
반응형
'00.AI' 카테고리의 다른 글
| [Ollama] Rocky 에서 Ollama 설치 및 활용 방법 (0) | 2026.02.12 |
|---|