gitlab-mcp

GitLab 16.x용 FastMCP 서버. 프로젝트·MR·파이프라인·커밋 조회, 버그 기여 요약·릴리즈 노트 초안, 그리고 Runners API 기반 Runner 관리 도구를 제공합니다.

노출 Tool (MCP)

프로젝트·MR 등 조회·요약 계열은 GitLab REST API GET 위주입니다. Runner 도구는 목록·상세 조회뿐 아니라 등록·토큰 재설정·할당/해제·설정 변경·삭제 등 POST / PUT / DELETE를 사용합니다. Runner 토큰만 쓰는 일부 호출(verify_runner_authentication 등)은 PRIVATE-TOKEN을 보내지 않습니다.

GitLab Runner 관련

Tool	파라미터	설명
list_runners	scope, runner_type, status, paused, tag_list, version_prefix, page, per_page	현재 사용자 기준 Runner 목록 (GET /runners)
list_all_runners	위와 동일	인스턴스 전체 Runner (GET /runners/all, 관리자/감사 권한)
get_runner	runner_id	Runner 상세 (GET /runners/:id)
update_runner	runner_id, description, paused, active, tag_list, run_untagged, locked, access_level, maximum_timeout, maintenance_note	Runner 설정 변경 (PUT /runners/:id, active보다 paused 권장)
delete_runner	runner_id	Runner 삭제 (DELETE /runners/:id)
list_runner_jobs	runner_id, system_id, status, order_by, sort, page, per_page	Runner가 처리한 Job 목록 (GET /runners/:id/jobs)
list_runner_managers	runner_id	Runner manager 목록 (GET /runners/:id/managers)
list_project_runners	project, scope, runner_type, status, paused, tag_list, version_prefix, page, per_page	프로젝트에 연결 가능한 Runner (GET /projects/:id/runners)
assign_runner_to_project	project, runner_id	프로젝트에 Runner 할당 (POST /projects/:id/runners)
unassign_runner_from_project	project, runner_id	프로젝트에서 Runner 해제 (DELETE /projects/:id/runners/:runner_id)
list_group_runners	group_id, runner_type, status, paused, tag_list, version_prefix, page, per_page	그룹 Runner 목록 (GET /groups/:id/runners)
create_runner_with_registration_token	registration_token, description, paused, active, locked, run_untagged, tag_list, access_level, maximum_timeout, maintenance_note, maintainer_note	등록 토큰으로 Runner 등록 (POST /runners, 레거시 비활성 시 410 가능)
delete_runner_by_authentication_token	authentication_token	인증 토큰으로 Runner 삭제 (DELETE /runners, PAT 미사용)
verify_runner_authentication	authentication_token, system_id	Runner 자격 검증 (POST /runners/verify, PAT 미사용; glrt- 토큰이면 system_id 필요할 수 있음)
reset_instance_runner_registration_token	(없음)	인스턴스 등록 토큰 재설정 (관리자)
reset_project_runner_registration_token	project	프로젝트 등록 토큰 재설정
reset_group_runner_registration_token	group_id	그룹 등록 토큰 재설정
reset_runner_authentication_token_by_runner_id	runner_id	Runner ID + PAT로 인증 토큰 재설정
reset_runner_authentication_token_by_current_token	authentication_token	현재 Runner 토큰으로 인증 토큰 재설정 (POST /runners/reset_authentication_token)
get_runner_job_router_discovery	authentication_token	Job Router discovery (GET /runners/router/discovery, Runner-Token 헤더)

프로젝트·MR·파이프라인·커밋·요약

Tool	파라미터	설명
list_projects	search, membership, owned, page, per_page	토큰으로 접근 가능한 프로젝트 목록
get_project	project_id, project_path (둘 중 하나)	프로젝트 상세; project_path는 URL 인코딩 경로·path_with_namespace·동일 호스트 웹 URL
list_merge_requests	project, state, source_branch, target_branch, labels, merged_after, merged_before, page, per_page	프로젝트 MR 목록
get_merge_request	project, mr_iid	단일 MR 상세
list_pipelines	project, ref, status, page, per_page	파이프라인 목록
get_pipeline	project, pipeline_id	단일 파이프라인 상세
get_job_trace	project, job_id	CI Job 콘솔 로그(plain text trace, GET /projects/:id/jobs/:job_id/trace; job_id는 숫자 id)
list_commits	project, ref_name, since, until, path, with_stats, page, per_page	커밋 이력
get_commit	project, sha, stats	단일 커밋 상세
compare_commits	project, from_ref, to_ref, straight	두 ref(브랜치/태그/SHA) 비교
summarize_bugfix_contribution	project, since, until, branch, bug_keywords, component_path_rules, top_n	기간 내 bugfix 추정 커밋으로 기여자·컴포넌트 요약
generate_release_notes	project, since, until, ref_name, categories, audience, max_items_per_category, max_commits_to_scan, include_merge_commits	기간 내 커밋 기준 고객용 릴리즈 노트 마크다운 초안

Requirements

• Python 3.11+
• GitLab 인증: Personal Access Token (GITLAB_TOKEN, read_api 권장) 또는 HTTP Basic (GITLAB_USERNAME + GITLAB_PASSWORD)

Install

python -m venv .venv
source .venv/bin/activate
pip install -e .

Configuration

GitLab REST API 인증은 다음 중 하나를 씁니다.

1. GITLAB_TOKEN — Personal Access Token. GitLab → Preferences → Access Tokens에서 발급, read_api 스코프 권장.
2. GITLAB_USERNAME + GITLAB_PASSWORD — HTTP Basic. 비밀번호 자리에는 계정 비밀번호 대신 PAT를 넣는 방식(GitLab 문서 허용)도 가능합니다.

우선순위: GITLAB_USERNAME과 GITLAB_PASSWORD가 둘 다 비어 있지 않으면 HTTP Basic만 사용하고, 그렇지 않으면 GITLAB_TOKEN의 PRIVATE-TOKEN 헤더를 사용합니다. 둘 다 없으면 인증 없이 공개 리소스만 호출합니다.

참고: GitLab.com에서 2FA가 켜진 계정은 일반 계정 비밀번호로 API가 거절되는 경우가 많습니다. 그때는 PAT(또는 OAuth)를 사용하세요. 셀프호스팅·2FA 없음 환경에서는 Basic이 동작할 수 있습니다.

GITLAB_USERNAME만 넣거나 GITLAB_PASSWORD만 넣은 채 GITLAB_TOKEN도 없으면 서버가 시작 시 오류를 냅니다.

설정은 프로세스 환경 변수로 넣습니다 (export … / Docker environment / 호스트에서 docker compose 실행 시 셸에 export한 값이 ${VAR} 로 전달).

변수	설명
GITLAB_BASE_URL	GitLab 베이스 URL (기본: https://gitlab.com)
GITLAB_TOKEN	Personal Access Token (PRIVATE-TOKEN 헤더; Basic 미사용 시)
GITLAB_USERNAME	HTTP Basic 사용자명 (비밀번호와 함께 사용)
GITLAB_PASSWORD	HTTP Basic 비밀번호 또는 PAT
GITLAB_TIMEOUT_SECONDS	API 타임아웃 초 (기본: 15)
GITLAB_DEFAULT_PER_PAGE	기본 페이지 크기 (기본: 20)
GITLAB_MAX_PER_PAGE	페이지 상한 (기본: 100)
MCP_TRANSPORT	stdio(기본) | http(Streamable HTTP) | sse
MCP_HOST	HTTP/SSE 바인드 주소 (기본: 127.0.0.1)
MCP_PORT	HTTP/SSE 포트 (기본: 8000)

Run (stdio, 로컬 기본)

gitlab-mcp

Run (Streamable HTTP, 로컬)

터미널에서 MCP 엔드포인트는 http://<MCP_HOST>:<MCP_PORT>/mcp 입니다 (예: http://127.0.0.1:8000/mcp).

export MCP_TRANSPORT=http MCP_HOST=127.0.0.1 MCP_PORT=8000
export GITLAB_BASE_URL="https://gitlab.example.com"
export GITLAB_TOKEN="<your_pat>"
gitlab-mcp

Run (Docker)

이미지는 HTTP(Streamable)로 뜨도록 되어 있습니다. 호스트에서 시크릿을 넣고 실행하려면 예를 들어:

export GITLAB_BASE_URL="https://gitlab.example.com"
export GITLAB_TOKEN="<your_pat>"
docker compose up --build

MCP URL은 http://<호스트>:<MCP_PORT>/mcp (기본 포트 8000) 입니다. 포트는 MCP_PORT 로 바꿀 수 있습니다.

Cursor MCP config example

stdio (로컬에서 프로세스로 실행):

{
  "mcpServers": {
    "gitlab-mcp-local": {
      "command": "gitlab-mcp"
    }
  }
}

Streamable HTTP (서버를 띄운 뒤 URL로 연결 — Cursor가 원격 MCP URL을 지원하는 경우):

{
  "mcpServers": {
    "gitlab-mcp-http": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Notes

• project 인자는 GitLab API 규칙에 맞게 URL 인코딩된 경로를 사용합니다 (예: group%2Frepo).
• Runner 도구는 GitLab Runners API 스펙과 권한(관리자·프로젝트 Maintainer 등)에 따릅니다. 토큰·등록 방식은 인스턴스 설정에 따라 동작이 달라질 수 있습니다.
• 프로젝트·MR·파이프라인 등 비 Runner 영역은 조회·요약 위주이며, 일반적인 리소스 변경용 쓰기 API는 범위에 두지 않았습니다.