npm package: @structured-world/gitlab-mcp
Description: Advanced GitLab MCP server
Author: Dmitry Prudnikov
Latest version: 7.2.0

# Advanced GitLab MCP server

[![npm version](https://img.shields.io/npm/v/@structured-world/gitlab-mcp)](https://www.npmjs.com/package/@structured-world/gitlab-mcp) [![npm downloads](https://img.shields.io/npm/dm/@structured-world/gitlab-mcp)](https://www.npmjs.com/package/@structured-world/gitlab-mcp) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) [![Release](https://github.com/structured-world/gitlab-mcp/workflows/Release/badge.svg)](https://github.com/structured-world/gitlab-mcp/actions) [![Coverage](https://codecov.io/gh/structured-world/gitlab-mcp/graph/badge.svg)](https://codecov.io/gh/structured-world/gitlab-mcp) [![Coverage Report](https://img.shields.io/badge/Coverage-Live%20Report-brightgreen?logo=github)](https://gitlab-mcp.sw.foundation/coverage/)

Advanced GitLab MCP server — 44 tools across 18 entity types with CQRS architecture, OAuth 2.1, and multiple transport modes.

[![Install in Claude Desktop](https://img.shields.io/badge/Claude_Desktop-Install_Extension-F97316?style=for-the-badge)](https://gitlab-mcp.sw.foundation/downloads/gitlab-mcp-7.2.0.mcpb)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_Server-007ACC?style=for-the-badge&logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22gitlab-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40structured-world%2Fgitlab-mcp%22%5D%7D)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_MCP_Server-24bfa5?style=for-the-badge&logo=visualstudiocode&logoColor=white)](vscode-insiders:mcp/install?%7B%22name%22%3A%22gitlab-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40structured-world%2Fgitlab-mcp%22%5D%7D)

## Quick Start

```json
{
  "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

## Highlights

- **44 tools** across 18 entity types — 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 multiple GitLab instances with per-instance OAuth and rate limiting
- **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`

## Documentation

Full documentation is available at **[gitlab-mcp.sw.foundation](https://gitlab-mcp.sw.foundation)**

| Section | Description |
|---------|-------------|
| [Installation](https://gitlab-mcp.sw.foundation/guide/installation/npm) | npm, Docker, VS Code, Codex |
| [Configuration](https://gitlab-mcp.sw.foundation/guide/configuration) | Environment variables, feature flags |
| [Multi-Instance](https://gitlab-mcp.sw.foundation/guide/multi-instance) | Connect to multiple GitLab instances |
| [Tool Reference](https://gitlab-mcp.sw.foundation/tools/) | All 44 tools with parameters |
| [OAuth Setup](https://gitlab-mcp.sw.foundation/security/oauth) | Team authentication with Claude |
| [TLS/HTTPS](https://gitlab-mcp.sw.foundation/advanced/tls) | Production deployment with SSL |
| [Customization](https://gitlab-mcp.sw.foundation/advanced/customization) | Tool descriptions, action filtering |
| [CLI Tools](https://gitlab-mcp.sw.foundation/cli/list-tools) | Browse and export tool documentation |

### Auto-generated Tool Reference

For the complete tool reference with parameters:

```bash
# View locally
yarn list-tools --detail

# Generate documentation
yarn list-tools --export --toc > docs/tools/api-reference.md
```

See the [Full API Reference](https://gitlab-mcp.sw.foundation/tools/api-reference) for the auto-generated tool documentation.

## Docker

```bash
# 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`/`failed` state), only the `manage_context` tool is exposed, with local actions such as `whoami`, `switch_profile`, and `set_scope` for diagnostics. During active reconnect (`connecting` state), 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 via `tools/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 `failed` state (no auto-reconnect). Mid-session token revocation is detected via an authenticated `HEAD /api/v4/user` check 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 to `failed` state 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) |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and PR guidelines.

## Support the Project

<div align="center">

![USDT TRC-20 Donation QR Code](assets/usdt-qr.svg)

USDT (TRC-20): `TFDsezHa1cBkoeZT5q2T49Wp66K8t2DmdA`

</div>

## License

Apache License 2.0 — see [LICENSE](LICENSE) for details.

Based on [zereight/gitlab-mcp](https://github.com/zereight/gitlab-mcp) (MIT). See [LICENSE.MIT](LICENSE.MIT).