MCP GitLab CrunchTools

GitLab 프로젝트, 병합 요청, 이슈, 파이프라인 및 검색을 위한 보안 MCP(Model Context Protocol) 서버입니다. 모든 GitLab 인스턴스(gitlab.com, 자체 호스팅 또는 엔터프라이즈)에서 작동합니다.

개요

이 MCP 서버는 다음과 같은 특징을 갖도록 설계되었습니다:

• 기본 보안 - 포괄적인 위협 모델링, 입력 검증 및 토큰 보호

• 타사 서비스 없음 - stdio를 통해 로컬에서 실행되며, API 토큰이 머신을 떠나지 않습니다

• 다중 인스턴스 - 구성 가능한 URL을 통해 gitlab.com, 자체 호스팅 GitLab 또는 엔터프라이즈 인스턴스에서 작동

• 크로스 플랫폼 - Linux, macOS 및 Windows에서 작동

• 자동 업데이트 - GitHub Actions가 CVE를 모니터링하고 종속성을 업데이트

• 컨테이너화 - Hummingbird Python 기본 이미지를 기반으로 한 quay.io/crunchtools/mcp-gitlab에서 제공

Related MCP server: gitlab-mcp-server

명명 규칙

Hummingbird를 사용하는 이유는?

컨테이너 이미지는 Project Hummingbird의 Hummingbird Python 기본 이미지를 기반으로 구축되었으며, 다음을 제공합니다:

• 최소 CVE 노출 - 최소 패키지 세트로 구축되어 공격 표면을 획기적으로 줄입니다

• 정기 업데이트 - 보안 패치가 신속하게 적용됩니다

• Python에 최적화 - uv 패키지 관리자가 사전 구성된 Python 환경

• 프로덕션 준비 - 적절한 신호 처리 및 비루트 사용자 기본값

기능

프로젝트 관리 (5개 도구)

• list_projects - 필터링 및 검색으로 프로젝트 나열

• get_project - ID 또는 경로로 프로젝트 세부 정보 가져오기

• list_project_branches - 저장소 분기 나열

• get_project_branch - 단일 분기 가져오기

• list_project_commits - 날짜/경로 필터링으로 커밋 나열

그룹 관리 (3개 도구)

• list_groups - 필터링으로 그룹 나열

• get_group - ID 또는 경로로 그룹 세부 정보 가져오기

• list_group_projects - 그룹의 프로젝트 나열 (하위 그룹 지원)

병합 요청 (7개 도구)

• list_merge_requests - 상태, 레이블, 마일스톤으로 MR 나열

• get_merge_request - MR 세부 정보 가져오기

• create_merge_request - 새 MR 생성

• update_merge_request - MR 제목, 설명, 상태, 담당자 업데이트

• list_mr_notes - MR의 댓글 나열

• create_mr_note - MR에 댓글 추가

• get_mr_changes - MR의 diff 가져오기

이슈 (6개 도구)

• list_issues - 상태, 레이블, 마일스톤, 담당자로 이슈 나열

• get_issue - 이슈 세부 정보 가져오기

• create_issue - 새 이슈 생성

• update_issue - 이슈 제목, 설명, 상태, 레이블 업데이트

• list_issue_notes - 이슈의 댓글 나열

• create_issue_note - 이슈에 댓글 추가

파이프라인 (4개 도구)

• list_pipelines - 상태 필터링으로 CI/CD 파이프라인 나열

• get_pipeline - 파이프라인 세부 정보 가져오기

• list_pipeline_jobs - 파이프라인의 작업 나열

• get_job_log - 작업 로그 출력 가져오기

검색 (2개 도구)

• search_global - 액세스 가능한 모든 GitLab 리소스에서 검색

• search_project - 특정 프로젝트 내에서 검색

설치

uvx 사용 (권장)

uvx mcp-gitlab-crunchtools

pip 사용

pip install mcp-gitlab-crunchtools

컨테이너 사용

podman run -e GITLAB_TOKEN=your_token \
    quay.io/crunchtools/mcp-gitlab

구성

환경 변수

GitLab 개인 액세스 토큰 만들기

1. 액세스 토큰으로 이동

   • https://gitlab.com/-/user_settings/personal_access_tokens로 이동

   • 또는: 아바타 > 기본 설정 > 액세스 토큰

2. 사용자 지정 토큰 만들기

   • 이름: mcp-gitlab-crunchtools

   • 만료일: 적절한 날짜 설정 (90일 권장)

   • 범위: 필요에 따라 범위 선택

3. 범위 선택

   범위	액세스 수준	기능
   read_api	읽기 전용	프로젝트, 이슈, MR, 파이프라인 보기/나열
   api	전체 액세스	생성/업데이트를 포함한 모든 기능

4. 토큰 복사 및 저장

   • 토큰을 즉시 복사 (glpat-로 시작)

   • 암호 관리자에 안전하게 저장

Claude Code에 추가

claude mcp add mcp-gitlab-crunchtools \
    --env GITLAB_TOKEN=your_token_here \
    -- uvx mcp-gitlab-crunchtools

자체 호스팅 GitLab의 경우:

claude mcp add mcp-gitlab-crunchtools \
    --env GITLAB_TOKEN=your_token_here \
    --env GITLAB_URL=https://gitlab.example.com \
    -- uvx mcp-gitlab-crunchtools

컨테이너 버전의 경우:

claude mcp add mcp-gitlab-crunchtools \
    --env GITLAB_TOKEN=your_token_here \
    -- podman run -i --rm -e GITLAB_TOKEN quay.io/crunchtools/mcp-gitlab

사용 예시

프로젝트 나열

User: List my GitLab projects
Assistant: [calls list_projects with membership=true]

병합 요청 보기

User: Show open merge requests for my-org/backend
Assistant: [calls list_merge_requests with project_id="my-org/backend"]

이슈 만들기

User: Create an issue in my-org/backend titled "Fix login timeout"
Assistant: [calls create_issue with title="Fix login timeout"]

파이프라인 상태 확인

User: Show failed pipelines for my-org/api
Assistant: [calls list_pipelines with status="failed"]

코드 검색

User: Search for "authentication" in my-org/backend
Assistant: [calls search_project with scope="blobs"]

보안

이 서버는 보안을 최우선으로 설계되었습니다. 자세한 내용은 SECURITY.md를 참조하세요:

• 위협 모델 및 공격 벡터

• 심층 방어 아키텍처

• 토큰 처리 모범 사례

• 입력 검증 규칙

• 감사 로깅

주요 보안 기능

1. 토큰 보호

   • SecretStr로 저장 (실수로 기록되지 않음)

   • 환경 변수로만 제공 (파일이나 인수에 절대 저장되지 않음)

   • 모든 오류 메시지에서 삭제 처리

2. 입력 검증

   • 모든 입력에 대한 Pydantic 모델

   • 프로젝트/그룹 ID에 대한 허용 목록 문자 검증

   • 경로 탐색 방지

3. API 강화

   • HTTPS 강제 (로컬호스트 제외)

   • TLS 인증서 검증

   • 요청 시간 제한 (30초)

   • 응답 크기 제한 (10MB)

4. 자동화된 CVE 스캔

   • GitHub Actions가 매주 종속성 스캔

   • Trivy를 사용한 컨테이너 보안 스캔

   • Python용 CodeQL 분석

개발

설정

git clone https://github.com/crunchtools/mcp-gitlab.git
cd mcp-gitlab
uv sync

테스트 실행

uv run pytest

린트 및 유형 검사

uv run ruff check src tests
uv run mypy src

컨테이너 빌드

podman build -t mcp-gitlab .

라이선스

AGPL-3.0-or-later

기여

기여를 환영합니다! 보안 관련 변경 사항을 제출하기 전에 SECURITY.md를 읽어주세요.

링크

• GitLab REST API 문서

• FastMCP 문서

• MCP 사양

• crunchtools.com