AI istemcilerinin GitLab projelerini, merge request'lerini, pipeline'larını ve iş öğelerini yapılandırılmış bir CQRS araç seti aracılığıyla yönetmesini sağlar.
Ayrıca bilinen adı structured-world/gitlab-mcp, gitlab-mcp, @structured-world/gitlab-mcp
- Yıldızlar
- 8
- Araçlar
- 4
- İndirmeler, 30 gün
- —
- En son sürüm
- 13.3.1
- Son commit
- 14 Kas 2026
- Lisans
- Apache-2.0
GitLab MCP nedir?
GitLab bir MCP sunucusudur. AI istemcilerinin GitLab projelerini, merge request'lerini, pipeline'larını ve iş öğelerini yapılandırılmış bir CQRS araç seti aracılığıyla yönetmesini sağlar. 4 araç sunar; örneğin browse_pipelines, manage_pipeline, browse_environments.
Özet, projenin README dosyasından oluşturuldu
GitLab MCP sunucusu hakkında
Bu sunucu, GitLab projelerini, merge request'lerini ve CI/CD pipeline'larını doğrudan bir AI istemcisi üzerinden yönetmenize olanak tanır. Claude Desktop, VS Code, Cursor veya Windsurf gibi istemciler kullanan geliştiriciler için yapılandırılmış bir araç seti sağlar. Sunucu, CQRS mimarisini kullanarak okuma amaçlı sorguları browse araçları ile yazma işlemlerini ise manage araçları üzerinden ayırır; böylece verileri incelemek ile komut yürütmek arasında net bir ayrım sağlar.
Kullanıcılar, bir GitLab token'ı veya OAuth 2.1 kimlik doğrulaması kullanarak GitLab.com, self-managed veya self-hosted örneklere bağlanabilirler. Sunucu oldukça adaptiftir; bağlı olan örneğin belirli GitLab sürümüne, katmanına ve token kapsamlarına göre 66 aracını ve 242 tipli aksiyonunu otomatik olarak filtreler. Bu sayede AI'nın desteklenmeyen işlemleri yapmaya çalışması engellenir. stdio, SSE ve StreamableHTTP dahil olmak üzere birden fazla taşıma yöntemini destekler ve Docker veya npm üzerinden dağıtılabilir.
Yüksek kullanılabilirlik gerektiren ekipler için, OAuth oturumlarını birden fazla replika arasında yönetmek üzere isteğe bağlı bir PostgreSQL backend mevcuttur. Sistem ayrıca, ağ kesintileri sırasında yeniden bağlanmak için üstel geri çekilme (exponential backoff) kullanan bağlantı dayanıklılığına ve GitLab örneğine ulaşılamadığında teşhis yeteneklerini koruyan bir bağlantısız mod özelliğine sahiptir.
Neler yapabilirsiniz
- 1CI/CD pipeline durumunu izlemeBir AI ajanı pipeline'ları listeleyebilir, belirli işleri (job) getirebilir ve hataları ayıklamak için logları çekebilir.
- 2Pipeline yaşam döngüsü komutlarını yürütmeGeliştiriciler, bir AI'ya pipeline'ları yeniden denetme, iptal etme veya yeni pipeline'lar oluşturma talimatı verebilir.
- 3Dağıtım ortamlarını yönetmeSunucu; ortamlar oluşturmaya, güncellemeye veya durdurmaya ve dağıtım durumlarını yönetmeye olanak tanır.
- 4Dağıtım anahtarlarını (deploy keys) yönetmeKullanıcılar, projeleri için dağıtım anahtarlarını listelemek, eklemek, etkinleştirmek veya silmek için AI'yı kullanabilirler.
Projenin README dosyasından alınmıştır. Her kullanım durumu, oradaki bir alıntı ile kontrol edilir.
GitLab MCP nasıl yüklenir
Biçimler 10 Kas 2026 tarihinde doğrulandıCursor'a ekleGoose'a ekleGitLab MCP'yi Claude Code içine yükleyin
$ claude mcp add --env 'GITLAB_TOKEN=<YOUR_GITLAB_TOKEN>' gitlab-mcp -- npx -y @structured-world/gitlab-mcpGitLab MCP'yi Cursor içine yükleyin
~/.cursor/mcp.json
{
"mcpServers": {
"gitlab-mcp": {
"command": "npx",
"args": [
"-y",
"@structured-world/gitlab-mcp"
],
"env": {
"GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>"
}
}
}
}GitLab MCP'yi VS Code içine yükleyin
.vscode/mcp.json
{
"servers": {
"gitlab-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@structured-world/gitlab-mcp"
],
"env": {
"GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>"
}
}
}
}GitLab MCP'yi VS Code CLI içine yükleyin
$ code --add-mcp '{"name":"gitlab-mcp","type":"stdio","command":"npx","args":["-y","@structured-world/gitlab-mcp"],"env":{"GITLAB_TOKEN":"<YOUR_GITLAB_TOKEN>"}}'GitLab MCP'yi Claude Desktop içine yükleyin
claude_desktop_config.json
{
"mcpServers": {
"gitlab-mcp": {
"command": "npx",
"args": [
"-y",
"@structured-world/gitlab-mcp"
],
"env": {
"GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>"
}
}
}
}GitLab MCP'yi Codex içine yükleyin
$ codex mcp add gitlab-mcp --env 'GITLAB_TOKEN=<YOUR_GITLAB_TOKEN>' -- npx -y @structured-world/gitlab-mcpGitLab MCP'yi Codex config.toml içine yükleyin
~/.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>"
GitLab MCP'yi Gemini CLI içine yükleyin
$ gemini mcp add -s user -e 'GITLAB_TOKEN=<YOUR_GITLAB_TOKEN>' gitlab-mcp npx -- -y @structured-world/gitlab-mcpGitLab MCP'yi Gemini settings.json içine yükleyin
~/.gemini/settings.json
{
"mcpServers": {
"gitlab-mcp": {
"command": "npx",
"args": [
"-y",
"@structured-world/gitlab-mcp"
],
"env": {
"GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>"
}
}
}
}GitLab MCP araçları 4
README dosyasından algılandıbrowse_pipelinesmanage_pipelinebrowse_environmentsmanage_environment
| browse_pipelines | — | |
| manage_pipeline | — | |
| browse_environments | — | |
| manage_environment | — |
Yapılandırma
GITLAB_TOKENGerekliGizliGitLab 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)
| Ad | Açıklama | Sunucu |
|---|---|---|
| GITLAB_TOKEN | GitLab Personal Access Token with 'api' and 'read_user' scopes | GerekliGizli |
| 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) |
Otomatik kontroller
Çalıştırıldı 12 Kas 2026Tam rapor →Otomatik kontrollerimizden geçti. Bu bir güvenlik denetimi değildir: kodu okuyun ve sunucuya ihtiyaç duyduğu en dar erişimi verin. Kontroller nasıl çalışır
- Kaynak deposu bağlantılı ve erişilebilirGeçti
- Açık kaynak lisansı (OSI)Geçti
- Son bir yıl içinde commit veya sürüm mevcutGeçti
- Paket adı popüler bir pakete yakın değilGeçti
- Uzak uç nokta HTTPS kullanıyorKontrol edilmedi
- Yıkıcı araçlar etiketlenmişGeçti
- Modele yönelik gizli talimat yokGeçti
- Pakette veya bağımlılıklarında kritik uyarı yokGeçti
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 soruları
GitLab MCP'yi Claude Code'a nasıl eklerim?
Terminalinizde claude mcp add --env 'GITLAB_TOKEN=<YOUR_GITLAB_TOKEN>' gitlab-mcp -- npx -y @structured-world/gitlab-mcp komutunu çalıştırın. Her projede kullanılabilir olması için --scope user ekleyin.
GitLab MCP'yi Cursor'a nasıl eklerim?
~/.cursor/mcp.json dosyasını açın ve yukarıdaki yükleme bölümünde gösterilen Cursor yapılandırmasını kullanarak sunucuyu mcpServers altına ekleyin.
GitLab MCP hangi araçları sunar?
4 araç sunar; bunlar arasında browse_pipelines, manage_pipeline, browse_environments, manage_environment yer alır.
GitLab MCP server içerisinde hangi araçlar yer alıyor?
Sunucu, 27 kayıt grubu üzerinden 66 araç sunar; buna 242 tipli aksiyona sahip 60 CQRS aracı ve 6 kurulum yardımcısı dahildir.
Birden fazla GitLab örneğine bağlanabilir miyim?
Evet, sunucu GitLab.com, self-managed ve self-hosted örnekleri için örnek başına OAuth ve hız sınırlama (rate limiting) desteğiyle çoklu örnek kullanımını destekler.
Sunucuyu çalıştırmak için sistem gereksinimleri nelerdir?
Sunucu, Node.js sürüm 24 veya üzerini gerektirir.