구조화된 CQRS 도구 세트를 통해 AI 클라이언트가 GitLab 프로젝트, merge requests, pipelines 및 work items를 관리할 수 있도록 지원합니다.
다른 이름 structured-world/gitlab-mcp, gitlab-mcp, @structured-world/gitlab-mcp
- 스타
- 8
- Tools
- 4
- 다운로드, 30일
- —
- 최신 버전
- 13.3.1
- 마지막 커밋
- 2026년 11월 14일
- 라이선스
- Apache-2.0
GitLab MCP란?
GitLab은(는) MCP server입니다. 구조화된 CQRS 도구 세트를 통해 AI 클라이언트가 GitLab 프로젝트, merge requests, pipelines 및 work items를 관리할 수 있도록 지원합니다. 4개 도구를 제공합니다. 예: browse_pipelines, manage_pipeline, browse_environments.
프로젝트 README에서 생성된 요약
GitLab MCP server 정보
이 서버는 AI 클라이언트에서 직접 GitLab 프로젝트, merge requests, CI/CD pipelines를 관리할 수 있게 해줍니다. Claude Desktop, VS Code, Cursor, Windsurf와 같은 클라이언트를 사용하는 개발자에게 구조화된 도구 세트를 제공합니다. CQRS 아키텍처를 활용하여 browse 도구를 통한 읽기 전용 쿼리와 manage 도구를 통한 쓰기 작업을 분리함으로써, 데이터 검사와 명령 실행 사이의 명확한 구분을 보장합니다.
사용자는 GitLab 토큰 또는 OAuth 2.1 인증을 사용하여 GitLab.com, self-managed 또는 self-hosted 인스턴스에 연결할 수 있습니다. 이 서버는 적응성이 매우 뛰어나 연결된 인스턴스의 특정 GitLab 버전, 티어 및 토큰 스코프에 따라 66개의 도구와 242개의 타입 지정 액션을 자동으로 필터링합니다. 이를 통해 AI가 지원되지 않는 작업을 시도하는 것을 방지합니다. stdio, SSE, streamable HTTP를 포함한 다양한 전송 방식을 지원하며 Docker 또는 npm을 통해 배포할 수 있습니다.
고가용성이 필요한 팀을 위해 여러 복제본(replica) 간에 OAuth 세션을 관리할 수 있는 선택 사항인 PostgreSQL 백엔드를 제공합니다. 또한 네트워크 장애 시 재연결을 위해 exponential backoff를 사용하는 연결 탄력성과, GitLab 인스턴스에 접속할 수 없을 때도 진단 기능을 유지하는 disconnected mode 기능을 갖추고 있습니다.
활용 사례
- 1CI/CD pipeline 상태 모니터링AI 에이전트가 pipelines 목록을 확인하고, 특정 jobs를 조회하며, 로그를 가져와 실패 원인을 디버깅할 수 있습니다.
- 2pipeline 생명주기 명령 실행개발자가 AI에게 pipelines 재시도, 취소 또는 신규 생성을 지시할 수 있습니다.
- 3배포 환경 관리서버를 통해 environments를 생성, 업데이트 또는 중지하고 배포 상태를 관리할 수 있습니다.
- 4배포 키 관리AI를 사용하여 프로젝트의 deploy keys 목록 확인, 추가, 활성화 또는 삭제를 수행할 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
GitLab MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 GitLab MCP 설치
$ claude mcp add --env 'GITLAB_TOKEN=<YOUR_GITLAB_TOKEN>' gitlab-mcp -- npx -y @structured-world/gitlab-mcpCursor에 GitLab MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"gitlab-mcp": {
"command": "npx",
"args": [
"-y",
"@structured-world/gitlab-mcp"
],
"env": {
"GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>"
}
}
}
}VS Code에 GitLab MCP 설치
.vscode/mcp.json
{
"servers": {
"gitlab-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@structured-world/gitlab-mcp"
],
"env": {
"GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>"
}
}
}
}VS Code CLI에 GitLab MCP 설치
$ code --add-mcp '{"name":"gitlab-mcp","type":"stdio","command":"npx","args":["-y","@structured-world/gitlab-mcp"],"env":{"GITLAB_TOKEN":"<YOUR_GITLAB_TOKEN>"}}'Claude Desktop에 GitLab MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"gitlab-mcp": {
"command": "npx",
"args": [
"-y",
"@structured-world/gitlab-mcp"
],
"env": {
"GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>"
}
}
}
}Codex에 GitLab MCP 설치
$ codex mcp add gitlab-mcp --env 'GITLAB_TOKEN=<YOUR_GITLAB_TOKEN>' -- npx -y @structured-world/gitlab-mcpCodex config.toml에 GitLab MCP 설치
~/.codex/config.toml
[mcp_servers.gitlab-mcp] command = "npx" args = ["-y", "@structured-world/gitlab-mcp"] [mcp_servers.gitlab-mcp.env] GITLAB_TOKEN = "<YOUR_GITLAB_TOKEN>"
Gemini CLI에 GitLab MCP 설치
$ gemini mcp add -s user -e 'GITLAB_TOKEN=<YOUR_GITLAB_TOKEN>' gitlab-mcp npx -- -y @structured-world/gitlab-mcpGemini settings.json에 GitLab MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"gitlab-mcp": {
"command": "npx",
"args": [
"-y",
"@structured-world/gitlab-mcp"
],
"env": {
"GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>"
}
}
}
}GitLab MCP 도구 4
README에서 감지됨browse_pipelinesmanage_pipelinebrowse_environmentsmanage_environment
| browse_pipelines | — | |
| manage_pipeline | — | |
| browse_environments | — | |
| manage_environment | — |
구성
GITLAB_TOKEN필수비밀GitLab Personal Access Token with 'api' and 'read_user' scopes
GITLAB_API_URLGitLab instance API URL for self-hosted instances (defaults to https://gitlab.com)
GITLAB_READ_ONLY_MODEEnable read-only mode (disable all manage_* write operations)
| 이름 | 설명 | 유형 |
|---|---|---|
| GITLAB_TOKEN | GitLab Personal Access Token with 'api' and 'read_user' scopes | 필수비밀 |
| GITLAB_API_URL | GitLab instance API URL for self-hosted instances (defaults to https://gitlab.com) | |
| GITLAB_READ_ONLY_MODE | Enable read-only mode (disable all manage_* write operations) |
자동 검사
2026년 11월 12일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능통과
- 오픈 소스 라이선스 (OSI)통과
- 최근 1년 내 커밋 또는 릴리스통과
- 패키지 이름이 인기 패키지와 유사하지 않음통과
- 원격 엔드포인트가 HTTPS 사용검사되지 않음
- 파괴적인 도구에 라벨 표시됨통과
- 모델에 대한 숨겨진 지침 없음통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음통과
README
GitHub에서 보기Advanced GitLab MCP server
Advanced GitLab MCP server: 66 tools across 27 registry groups, including 60 CQRS tools with 242 typed actions and 6 setup helpers. The tool catalog and parameters are filtered to each instance's GitLab version, tier, and token scopes, so the agent sees only what the connected instance actually supports.
Packages
This is a monorepo with two npm packages:
@structured-world/gitlab-mcp— the MCP server. In-memory and file OAuth-session storage, no database dependency. This is all most users need.@structured-world/gitlab-mcp-db— optional PostgreSQL/Prisma OAuth-session backend for running multiple replicas behind a load balancer. Enable it withOAUTH_STORAGE_TYPE=postgresql; see the PostgreSQL deployment guide for the full setup.
Quick Start
{
"mcpServers": {
"gitlab": {
"command": "npx",
"args": ["-y", "@structured-world/gitlab-mcp"],
"env": {
"GITLAB_TOKEN": "your_gitlab_token",
"GITLAB_API_URL": "https://gitlab.com"
}
}
}
}
Requirements: Node.js >= 24
GitLab Duo sessions
GitLab Duo sessions are also supported: discover agents and flows, inspect progress and outputs, and explicitly start or answer asynchronous CI sessions. Commands can consume credits and change GitLab. See the Duo session guide.
Supported clients
| Client | Setup |
|---|---|
| Codex (CLI and desktop) | Configurable local plugin, local MCP registration or HTTP server |
Antigravity CLI (agy) |
Workspace MCP configuration and tested compatibility |
| Claude Desktop | Desktop extension or MCP configuration |
| Claude Code | CLI or MCP configuration |
| VS Code | MCP configuration |
| Cursor | MCP configuration |
| Windsurf | MCP configuration |
| Cline | MCP configuration |
| Roo Code | MCP configuration |
The Codex plugin can be installed before configuring a target. Its connection panel supports a GitLab instance with a locally started core server, or an existing HTTP MCP server. The local plugin requires Node.js 24+; credentials are entered in its private panel. See the installation guide for marketplace setup and authentication.
The shared sw.foundation marketplace lists
verified releases. Add it once with codex plugin marketplace add structured-world/repo --sparse .agents/plugins,
then install GitLab MCP from that catalog after its first configurable plugin release.
Download the ready-made Codex marketplace ZIP and its SHA-256 checksum from GitHub Releases. It includes the local runtime and dependencies, separately from the Claude Desktop MCPB bundles. Add the extracted marketplace once, then install through Codex. An install link requires an already configured marketplace; downloading the ZIP does not install it automatically. Older releases may not contain these assets.
With the Codex CLI installed and GITLAB_API_URL and GITLAB_TOKEN set in your
environment, run npx @structured-world/gitlab-mcp install --codex to register a
local server. For Antigravity, add the server
to .agents/mcp_config.json in your workspace. Follow the linked guides for
authentication, remote-server setup and client-specific configuration.
Codex and Claude Code can be configured side by side. Antigravity CLI 1.4.10 is qualified against the installed core package on macOS and Linux, including empty and single-MR lists. See the client overview for all setup guides.
Highlights
- 66 tools across 27 registry groups: projects, merge requests, pipelines, work items, wiki, and more
- CQRS architecture —
browse_*for queries,manage_*for commands - Connection resilience — Bounded startup, auto-reconnect with exponential backoff, disconnected mode when GitLab is unreachable
- Multi-instance support — Connect to GitLab.com, self-managed, and self-hosted instances with per-instance OAuth and rate limiting; one connection can link several accounts, such as a company GitLab and a personal GitLab.com account, and each chat switches between them
- Multiple transports — stdio, SSE, StreamableHTTP
- OAuth 2.1 — Per-user authentication via Claude Custom Connector
- Read-only mode — Safe operation for production environments
- Auto-discovery — Detects GitLab config from git remotes
- Fine-grained control — Enable/disable tool groups, filter actions, customize descriptions
- Docker support —
ghcr.io/structured-world/gitlab-mcp:latest
Tool model
GitLab exposes hundreds of API operations. Giving each its own MCP tool floods an agent's context; a thin API wrapper pushes that complexity back onto the agent. This server takes a third path: 60 CQRS tools expose 242 typed actions, with 6 additional helpers for account, connection and settings work. The complete catalog contains 66 tools across 27 registry groups. This total includes core and account/context tools. Settings expose a different set of configurable tool groups: core and context tools are always available, and CI job tokens and deploy keys share one switch.
browse_*tools are read-only queries;manage_*tools are writes.- Sub-resources fold into actions rather than new tools —
browse_pipelinescovers pipelines, jobs, and logs in a single tool. - The tool list, actions, and parameters are resolved at schema-generation time against GitLab version, tier, token scopes, admin-mode, feature flags, and profiles.
Examples:
browse_pipelines— list, get, jobs, job, logs, triggersmanage_pipeline— create, retry, cancelbrowse_environments— list, get, list_deploymentsmanage_environment— create, update, stop, delete, update_deployment_statusbrowse_deploy_keys/manage_deploy_key— list, get / add, enable, update, delete
Documentation
Full documentation is available at gitlab-mcp.sw.foundation
| Section | Description |
|---|---|
| Installation | npm, Docker, VS Code, Codex |
| Configuration | Environment variables, feature flags |
| Multi-Instance | Connect to multiple GitLab instances |
| Tool Reference | All 66 tools with parameters |
| OAuth Setup | Team authentication with Claude |
| TLS/HTTPS | Production deployment with SSL |
| Customization | Tool descriptions, action filtering |
| CLI Tools | Browse and export tool documentation |
Auto-generated Tool Reference
For the complete tool reference with parameters:
# View locally
yarn list-tools --detail
# Generate documentation
yarn list-tools --export --toc > docs/tools/api-reference.md
See the Full API Reference for the auto-generated tool documentation.
Docker
# HTTP mode
docker run -e PORT=3002 -e GITLAB_TOKEN=your_token -p 3333:3002 \
ghcr.io/structured-world/gitlab-mcp:latest
# stdio mode
docker run -i --rm -e GITLAB_TOKEN=your_token \
ghcr.io/structured-world/gitlab-mcp:latest
Connection Resilience
The server handles GitLab connectivity issues gracefully:
- Bounded startup — Server starts within
GITLAB_INIT_TIMEOUT_MS(default 5s) regardless of GitLab availability - Disconnected mode — When GitLab is unreachable (
disconnected/failedstate), only themanage_contexttool is exposed, with local actions such aswhoami,switch_preset, andset_scopefor diagnostics. During active reconnect (connectingstate), the full tool list remains available so MCP clients don't lose their tool catalog during brief outages. MCP clients are notified of tool availability changes viatools/list_changed - Auto-reconnect — Exponential backoff reconnection (5s → 60s) with ±10% jitter
- Error classification — Transient errors (network, 5xx, timeouts) trigger auto-reconnect. Auth/config errors at startup transition to
failedstate (no auto-reconnect). Mid-session token revocation is detected via an authenticatedHEAD /api/v4/usercheck that runs alongside each periodic health check (static token mode only; skipped in OAuth mode). A 401 or 403 on this check transitions the instance tofailedstate immediately. - Instance health monitor — Each monitored instance URL has its own XState state machine. Untracked OAuth URLs currently pass through as reachable.
| Variable | Default | Description |
|---|---|---|
GITLAB_INIT_TIMEOUT_MS |
5000 |
Max time to wait for GitLab during startup |
GITLAB_RECONNECT_BASE_DELAY_MS |
5000 |
Initial reconnect delay (doubles each attempt) |
GITLAB_RECONNECT_MAX_DELAY_MS |
60000 |
Maximum reconnect delay |
GITLAB_HEALTH_CHECK_INTERVAL_MS |
60000 |
Health check interval when connected |
GITLAB_FAILURE_THRESHOLD |
3 |
Consecutive transient failures before disconnecting |
GITLAB_TOOL_TIMEOUT_MS |
120000 |
Max time for tool/bootstrap execution before timeout |
GITLAB_RESPONSE_WRITE_TIMEOUT_MS |
10000 |
Max time to flush a non-SSE response before destroying zombie connection (0 to disable; SSE uses heartbeat) |
GITLAB_INSTANCE_CACHE_MAX |
100 |
Max number of per-URL instance states kept in memory (OAuth multi-tenant; LRU eviction when exceeded) |
GITLAB_INSTANCE_TTL_MS |
3600000 |
TTL for idle per-URL instance states in ms; evicted on next insert (OAuth multi-tenant) |
Feature Flags
| Flag | Default | Tools Enabled |
|---|---|---|
USE_LABELS |
true |
Label management |
USE_MRS |
true |
Merge requests |
USE_FILES |
true |
File operations |
USE_VARIABLES |
true |
CI/CD variables |
USE_WORKITEMS |
true |
Issues, epics, tasks |
USE_WEBHOOKS |
true |
Webhook management |
USE_SNIPPETS |
true |
Code snippets |
USE_INTEGRATIONS |
true |
50+ integrations |
USE_GITLAB_WIKI |
true |
Wiki pages |
USE_MILESTONE |
true |
Milestones |
USE_PIPELINE |
true |
Pipelines & CI/CD |
USE_RELEASES |
true |
Release management |
USE_REFS |
true |
Branch & tag management |
USE_MEMBERS |
true |
Team members |
USE_SEARCH |
true |
Cross-project search |
USE_ITERATIONS |
true |
Iteration planning (sprints) |
USE_CI_TOKENS |
true |
CI access credentials: job token scope and deploy keys |
USE_ENVIRONMENTS |
true |
Environments and deployments |
USE_RUNNERS |
true |
CI runner management |
USE_REGISTRY |
true |
Container registry repositories and tags |
USE_ACCESS_TOKENS |
true |
Project/group/personal access token management |
USE_AUDIT_EVENTS |
true |
Audit events (Premium+) |
USE_VULNERABILITIES |
true |
Vulnerability management (Ultimate) |
Contributing
See CONTRIBUTING.md for development setup, testing, and PR guidelines.
Support the Project
USDT (TRC-20): TFDsezHa1cBkoeZT5q2T49Wp66K8t2DmdA
License
Apache License 2.0 — see LICENSE for details.
Based on zereight/gitlab-mcp (MIT). See LICENSE.MIT.
GitLab MCP 질문
GitLab MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add --env 'GITLAB_TOKEN=<YOUR_GITLAB_TOKEN>' gitlab-mcp -- npx -y @structured-world/gitlab-mcp를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
GitLab MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
GitLab MCP는 어떤 도구를 제공하나요?
4개 도구를 제공합니다. 예: browse_pipelines, manage_pipeline, browse_environments, manage_environment.
GitLab MCP server에는 어떤 도구들이 포함되어 있나요?
이 서버는 27개 레지스트리 그룹에 걸쳐 66개의 도구를 제공하며, 여기에는 242개의 타입 지정 액션(typed actions)을 포함한 60개의 CQRS 도구와 6개의 설정 헬퍼가 포함됩니다.
여러 GitLab 인스턴스에 연결할 수 있나요?
네, 이 서버는 GitLab.com, self-managed 및 self-hosted 인스턴스에 대한 멀티 인스턴스 지원을 제공하며, 인스턴스별 OAuth 및 rate limiting을 지원합니다.
서버 실행을 위한 시스템 요구 사항은 무엇인가요?
서버를 실행하려면 Node.js 버전 24 이상이 필요합니다.