gitlab-mcp
Provides tools for interacting with GitLab's API, enabling management of projects, merge requests, pipelines, commits, and runners, including listing, creating, updating, and deleting resources.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gitlab-mcp list my open merge requests in project my-group/my-project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 | 파라미터 | 설명 |
|
| 현재 사용자 기준 Runner 목록 ( |
| 위와 동일 | 인스턴스 전체 Runner ( |
|
| Runner 상세 ( |
|
| Runner 설정 변경 ( |
|
| Runner 삭제 ( |
|
| Runner가 처리한 Job 목록 ( |
|
| Runner manager 목록 ( |
|
| 프로젝트에 연결 가능한 Runner ( |
|
| 프로젝트에 Runner 할당 ( |
|
| 프로젝트에서 Runner 해제 ( |
|
| 그룹 Runner 목록 ( |
|
| 등록 토큰으로 Runner 등록 ( |
|
| 인증 토큰으로 Runner 삭제 ( |
|
| Runner 자격 검증 ( |
| (없음) | 인스턴스 등록 토큰 재설정 (관리자) |
|
| 프로젝트 등록 토큰 재설정 |
|
| 그룹 등록 토큰 재설정 |
|
| Runner ID + PAT로 인증 토큰 재설정 |
|
| 현재 Runner 토큰으로 인증 토큰 재설정 ( |
|
| Job Router discovery ( |
프로젝트·MR·파이프라인·커밋·요약
Tool | 파라미터 | 설명 |
|
| 토큰으로 접근 가능한 프로젝트 목록 |
|
| 프로젝트 상세; |
|
| 프로젝트 MR 목록 |
|
| 단일 MR 상세 |
|
| 파이프라인 목록 |
|
| 단일 파이프라인 상세 |
|
| CI Job 콘솔 로그(plain text trace, |
|
| 커밋 이력 |
|
| 단일 커밋 상세 |
|
| 두 ref(브랜치/태그/SHA) 비교 |
|
| 기간 내 bugfix 추정 커밋으로 기여자·컴포넌트 요약 |
|
| 기간 내 커밋 기준 고객용 릴리즈 노트 마크다운 초안 |
Related MCP server: gitlab-api
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 인증은 다음 중 하나를 씁니다.
GITLAB_TOKEN— Personal Access Token. GitLab → Preferences → Access Tokens에서 발급,read_api스코프 권장.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 베이스 URL (기본: |
| Personal Access Token ( |
| HTTP Basic 사용자명 (비밀번호와 함께 사용) |
| HTTP Basic 비밀번호 또는 PAT |
| API 타임아웃 초 (기본: |
| 기본 페이지 크기 (기본: |
| 페이지 상한 (기본: |
|
|
| HTTP/SSE 바인드 주소 (기본: |
| HTTP/SSE 포트 (기본: |
Run (stdio, 로컬 기본)
gitlab-mcpRun (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-mcpRun (Docker)
이미지는 HTTP(Streamable)로 뜨도록 되어 있습니다. 호스트에서 시크릿을 넣고 실행하려면 예를 들어:
export GITLAB_BASE_URL="https://gitlab.example.com"
export GITLAB_TOKEN="<your_pat>"
docker compose up --buildMCP 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는 범위에 두지 않았습니다.
Available Tools
33 toolsassign_runner_to_projectB
Assign a project runner to a project (POST /projects/:id/runners).
Inputs: project (required), runner_id (required). Returns: object
compare_commitsB
Compare two refs (branch/tag/sha) in a project.
Inputs: to_ref (required), project (required), from_ref (required), straight. Returns: object
create_runner_with_registration_tokenB
Register a runner with a registration token (POST /runners). May return 410 if legacy registration is disabled.
Inputs: registration_token (required), active, locked, paused, +7 more. Returns: object
delete_runnerA
Delete a runner by ID (DELETE /runners/:id).
Inputs: runner_id (required). Returns: object
delete_runner_by_authentication_tokenA
Delete a runner using its authentication token (DELETE /runners with token). Does not use PRIVATE-TOKEN.
Inputs: authentication_token (required). Returns: object
generate_release_notesB
Generate customer-facing release notes from commits in a time range.
Inputs: since (required), until (required), project (required), audience, +5 more. Returns: object
get_commitC
Get commit details from a project.
Inputs: sha (required), project (required), stats. Returns: object
get_gitlab_connection_infoA
Report which GitLab host/base URL this MCP is configured to use (from env), plus API v4 URL, auth mode, and MCP server bind settings. Does not expose tokens or passwords.
Inputs: no named parameters. Returns: object
get_job_traceA
Get plain-text CI job log (trace) for a project job (GET /projects/:id/jobs/:job_id/trace).
Inputs: job_id (required), project (required). Returns: object
get_merge_requestC
Get merge request details from a project.
Inputs: mr_iid (required), project (required). Returns: object
get_pipelineC
Get pipeline details from a project.
Inputs: project (required), pipeline_id (required). Returns: object
get_projectA
Get project details by id, path_with_namespace, or project web URL (same host as GITLAB_BASE_URL).
Inputs: project_id, project_path. Returns: object
get_runnerA
Get details for a runner by ID (GET /runners/:id).
Inputs: runner_id (required). Returns: object
get_runner_job_router_discoveryC
Job Router discovery (GET /runners/router/discovery) using Runner-Token header.
Inputs: authentication_token (required). Returns: object
list_all_runnersA
List all runners on the instance (GET /runners/all). Requires admin or auditor.
Inputs: page, scope, paused, status, +4 more. Returns: object
list_commitsC
List commits for a project.
Inputs: project (required), page, path, since, +4 more. Returns: object
list_group_runnersC
List runners for a group (GET /groups/:id/runners).
Inputs: group_id (required), page, paused, status, +4 more. Returns: object
list_merge_requestsC
List merge requests for a project.
Inputs: project (required), page, state, labels, +5 more. Returns: object
list_pipelinesB
List pipelines for a project.
Inputs: project (required), ref, page, status, +1 more. Returns: object
list_project_runnersC
List runners available to a project (GET /projects/:id/runners).
Inputs: project (required), page, scope, paused, +5 more. Returns: object
list_projectsC
List projects visible to the token.
Inputs: page, owned, search, per_page, +1 more. Returns: object
list_runner_jobsC
List jobs processed by a runner (GET /runners/:id/jobs).
Inputs: runner_id (required), page, sort, status, +3 more. Returns: object
list_runner_managersA
List runner managers (version, platform, system_id) for a runner (GET /runners/:id/managers).
Inputs: runner_id (required). Returns: object
list_runnersC
List runners available to the current user (GET /runners).
Inputs: page, scope, paused, status, +4 more. Returns: object
reset_group_runner_registration_tokenB
Reset a group's runner registration token.
Inputs: group_id (required). Returns: object
reset_instance_runner_registration_tokenB
Reset the instance runner registration token (admin).
Inputs: no named parameters. Returns: object
reset_project_runner_registration_tokenB
Reset a project's runner registration token.
Inputs: project (required). Returns: object
reset_runner_authentication_token_by_current_tokenB
Reset a runner authentication token using the current token (POST /runners/reset_authentication_token).
Inputs: authentication_token (required). Returns: object
reset_runner_authentication_token_by_runner_idA
Reset a runner authentication token using the runner ID and PRIVATE-TOKEN (POST /runners/:id/reset_authentication_token).
Inputs: runner_id (required). Returns: object
summarize_bugfix_contributionC
Summarize bugfix contributors and most changed components.
Inputs: since (required), until (required), project (required), top_n, +3 more. Returns: object
unassign_runner_from_projectA
Unassign a runner from a project (DELETE /projects/:id/runners/:runner_id).
Inputs: project (required), runner_id (required). Returns: object
update_runnerC
Update runner settings (PUT /runners/:id). Prefer paused over active.
Inputs: runner_id (required), active, locked, paused, +6 more. Returns: object
verify_runner_authenticationB
Verify runner credentials (POST /runners/verify). Uses the runner token only, not PRIVATE-TOKEN.
Inputs: authentication_token (required), system_id. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 33 tools
Each tool targets a distinct resource and action. The runner-related tools are clearly differentiated by scope (user, all, project, group) and operation (list, get, update, delete, assign, unassign, reset, verify). Even similar reset token tools specify their method (by runner ID vs. current token) in the name.
All tool names follow a consistent verb_noun pattern using snake_case, such as get_project, list_merge_requests, update_runner, and reset_runner_authentication_token_by_current_token. The naming is predictable and easy to navigate, despite some longer composite names.
With 33 tools, the server exceeds the 25-tool threshold for 'too many'. While GitLab has a broad API, the set includes a very large number of runner-specific endpoints (about 20 runner-related tools) plus two unusual analytics tools, making the overall surface feel overloaded and less focused.
The server is heavily read-oriented for core resources (projects, merge requests, pipelines, commits) and lacks create/update/delete operations for these. Runner management is comprehensive, but the overall GitLab domain is incomplete—agents cannot create a project, update or merge a merge request, or cancel a pipeline, leaving significant gaps.
Related MCP Connectors
Go MCP server for GitLab: 2 dynamic tools reach 1000+ REST/GraphQL actions. Free/CE, no paid tier.
GitLab MCP — wraps the GitLab REST API v4 (BYO API key)
A MCP server built for developers enabling Git based project management with project and personal…
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMCP server for interacting with GitLab API, supporting both self-hosted instances and gitlab.com. Provides tools for managing issues, merge requests, code review, pipelines, milestones, releases, search, and file access.2,012 npmMIT
- AlicenseCqualityBmaintenanceMCP server for interacting with GitLab API, supporting dynamic tool selection and enterprise-grade security.20810MIT
- AlicenseCqualityBmaintenanceA production-ready MCP server for GitLab enabling AI assistants to read and manage GitLab projects, merge requests, issues, pipelines, wikis, releases, and more through a unified interface.2682,012 npm10MIT
- AlicenseAqualityCmaintenanceMCP server for GitLab REST API enabling AI agents to manage pipelines, merge requests, diffs, and local reviews.159 npmMIT