gitlab-mcp

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 (로컬에서 프로세스로 실행): ``json { "mcpServers": { "gitlab-mcp-local": { "command": "gitlab-mcp" } } } ``

Streamable HTTP (서버를 띄운 뒤 URL로 연결 — Cursor가 원격 MCP URL을 지원하는 경우): ``json { "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는 범위에 두지 않았습니다.