# Advanced GitLab MCP server
[](https://www.npmjs.com/package/@structured-world/gitlab-mcp) [](https://www.npmjs.com/package/@structured-world/gitlab-mcp) [](LICENSE) [](https://github.com/structured-world/gitlab-mcp/actions) [](https://codecov.io/gh/structured-world/gitlab-mcp) [](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.
[](https://gitlab-mcp.sw.foundation/downloads/gitlab-mcp-6.61.0.mcpb)
[](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)
[](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
- **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
```
## 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): `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).
