# GitLab MCP server

> Enables AI clients to manage GitLab projects, merge requests, pipelines, and work items through a structured CQRS toolset.

- Repository: https://github.com/structured-world/gitlab-mcp
- Page: https://hostedmcp.org/servers/structured-world/gitlab-mcp
- Transport: stdio
- Stars: 8
- License: Apache-2.0
- Latest version: 13.3.1

## Install

### Claude Code

```sh
claude mcp add --env 'GITLAB_TOKEN=<YOUR_GITLAB_TOKEN>' gitlab-mcp -- npx -y @structured-world/gitlab-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@structured-world/gitlab-mcp"
      ],
      "env": {
        "GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "gitlab-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@structured-world/gitlab-mcp"
      ],
      "env": {
        "GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"gitlab-mcp","type":"stdio","command":"npx","args":["-y","@structured-world/gitlab-mcp"],"env":{"GITLAB_TOKEN":"<YOUR_GITLAB_TOKEN>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@structured-world/gitlab-mcp"
      ],
      "env": {
        "GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add gitlab-mcp --env 'GITLAB_TOKEN=<YOUR_GITLAB_TOKEN>' -- npx -y @structured-world/gitlab-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```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

```sh
gemini mcp add -s user -e 'GITLAB_TOKEN=<YOUR_GITLAB_TOKEN>' gitlab-mcp npx -- -y @structured-world/gitlab-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@structured-world/gitlab-mcp"
      ],
      "env": {
        "GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `GITLAB_TOKEN` | yes | yes | GitLab Personal Access Token with 'api' and 'read_user' scopes |
| `GITLAB_API_URL` | no | no | GitLab instance API URL for self-hosted instances (defaults to https://gitlab.com) |
| `GITLAB_READ_ONLY_MODE` | no | no | Enable read-only mode (disable all manage_* write operations) |

## Tools (4)

- `browse_pipelines`
- `manage_pipeline`
- `browse_environments`
- `manage_environment`

## FAQ

### What tools are included in the GitLab MCP server?

The server provides 66 tools across 27 registry groups, including 60 CQRS tools with 242 typed actions and 6 setup helpers.

### Can I connect to multiple GitLab instances?

Yes, the server supports multi-instance support for GitLab.com, self-managed, and self-hosted instances with per-instance OAuth and rate limiting.

### What are the system requirements for running the server?

The server requires Node.js version 24 or higher.