gitlab-mcp

# GitLab MCP Server

[English](./README.md) | [한국어](./README.ko.md) | [简体中文](./README.zh-CN.md)

📖 **[Documentation →](https://zereight.github.io/gitlab-mcp/)** Setup guides, environment variables, and the full tool reference live on the hosted docs site.

> **New Feature**: Dynamic GitLab API URL support with connection pooling! See [Dynamic API URL Documentation](docs/configuration/dynamic-api-url.md) for details.

[![Star History Chart](https://api.star-history.com/svg?repos=zereight/gitlab-mcp&type=Date)](https://www.star-history.com/#zereight/gitlab-mcp&Date)

## @zereight/mcp-gitlab

A comprehensive GitLab MCP server for AI clients. Manage projects, merge requests, issues, pipelines, wiki, releases, tags, milestones, and more through stdio, SSE, and Streamable HTTP.

Supports PAT, OAuth, read-only mode, dynamic API URLs, and remote authorization for VS Code, Claude, Cursor, Copilot, and other MCP clients.

### Why use this GitLab MCP?

- Broad GitLab coverage — projects, repository browsing, merge requests, issues, pipelines, wiki, releases, tags, labels, milestones, and more
- Flexible auth — Personal Access Token, local OAuth2 browser flow, MCP OAuth proxy, and per-request remote authorization
- Multiple transports — stdio for local clients, SSE for legacy clients, and Streamable HTTP for modern remote deployments
- Client-friendly setup — examples for Claude Code, Codex, Antigravity, OpenCode, Copilot, Cline, Roo Code, Cursor, Kilo Code, and Amp Code
- Self-hosted ready — works with custom GitLab instances, proxy settings, and dynamic API URL routing

Quick start: choose either Personal Access Token or OAuth2 setup below and use `@zereight/mcp-gitlab` in your MCP client configuration.

### Client Setup Guides

- [Claude Code Setup Guide](./docs/clients/claude-code.md)
- [VS Code Setup Guide](./docs/clients/vscode.md)
- [GitHub Copilot Setup Guide](./docs/clients/copilot.md)
- [Codex Setup Guide](./docs/clients/codex.md)
- [Cursor Setup Guide](./docs/clients/cursor.md)
- [JSON-Based MCP Clients Setup Guide](./docs/clients/json-clients.md) - for Factory AI Droid, OpenClaw, and OpenCode style clients
- [OAuth2 Authentication Setup Guide](./docs/auth/oauth-setup.md)
- [Environment Variables Reference](./docs/configuration/environment-variables.md)
- [Stateless Mode — Multi-Pod HPA](./docs/configuration/stateless-mode.md)
- [Custom Agents and Multiple PAT Setup](./docs/auth/custom-agent-multiple-pat.md)

## Usage

### Setup Overview

#### Authentication Methods

The server supports four authentication methods:

**For local/desktop use** (most common):

1. **Personal Access Token** (`GITLAB_PERSONAL_ACCESS_TOKEN`) — simplest setup
2. **OAuth2 — Local Browser** (`GITLAB_USE_OAUTH`) — recommended for better security

**For server/remote deployments**:

3. **OAuth2 — MCP Proxy** (`GITLAB_MCP_OAUTH`) — for remote MCP clients such as Claude.ai
4. **Remote Authorization** (`REMOTE_AUTHORIZATION`) — multi-user deployments where each caller provides their own token

#### Quick setup paths

- **Claude Code**: see [Claude Code Setup Guide](./docs/clients/claude-code.md)
- **VS Code**: see [VS Code Setup Guide](./docs/clients/vscode.md)
- **GitHub Copilot**: see [GitHub Copilot Setup Guide](./docs/clients/copilot.md)
- **Codex**: see [Codex Setup Guide](./docs/clients/codex.md)
- **Cursor**: see [Cursor Setup Guide](./docs/clients/cursor.md)
- **Factory AI Droid / OpenClaw / OpenCode style clients**: see [JSON-Based MCP Clients Setup Guide](./docs/clients/json-clients.md)
- **OAuth browser flow details**: see [OAuth2 Authentication Setup Guide](./docs/auth/oauth-setup.md)

For the simplest local setup, start with a Personal Access Token. For browser-based local auth, use OAuth2. For remote or multi-user deployments, continue to the MCP OAuth and Remote Authorization sections later in this README.

#### Using CLI Arguments (for clients with env var issues)

Some MCP clients (like GitHub Copilot CLI) have issues with environment variables. Use CLI arguments instead:

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab",
        "--token=YOUR_GITLAB_TOKEN",
        "--api-url=https://gitlab.com/api/v4"
      ],
      "tools": ["*"]
    }
  }
}
```

**Available CLI arguments:**

- `--token` - GitLab Personal Access Token (replaces `GITLAB_PERSONAL_ACCESS_TOKEN`)
- `--api-url` - GitLab API URL (replaces `GITLAB_API_URL`)
- `--read-only=true` - Enable read-only mode (replaces `GITLAB_READ_ONLY_MODE`)
- `--use-wiki=true` - Enable wiki API (replaces `USE_GITLAB_WIKI`)
- `--use-milestone=true` - Enable milestone API (replaces `USE_MILESTONE`)
- `--use-pipeline=true` - Enable pipeline API (replaces `USE_PIPELINE`)

CLI arguments take precedence over environment variables.

- sse

```shell
docker run -i --rm \
  -e HOST=0.0.0.0 \
  -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_READ_ONLY_MODE=true \
  -e USE_GITLAB_WIKI=true \
  -e USE_MILESTONE=true \
  -e USE_PIPELINE=true \
  -e SSE=true \
  -p 3333:3002 \
  zereight050/gitlab-mcp
```

```json
{
  "mcpServers": {
    "gitlab": {
      "type": "sse",
      "url": "http://localhost:3333/sse"
    }
  }
}
```

- streamable-http

```shell
docker run -i --rm \
  -e HOST=0.0.0.0 \
  -e REMOTE_AUTHORIZATION=true \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_READ_ONLY_MODE=true \
  -e USE_GITLAB_WIKI=true \
  -e USE_MILESTONE=true \
  -e USE_PIPELINE=true \
  -e STREAMABLE_HTTP=true \
  -p 3333:3002 \
  zereight050/gitlab-mcp
```

```json
{
  "mcpServers": {
    "gitlab": {
      "type": "streamable-http",
      "url": "http://localhost:3333/mcp",
      "headers": {
        "Authorization": "Bearer glpat-..."
      }
    }
  }
}
```

#### Using MCP OAuth Proxy (`GITLAB_MCP_OAUTH`)

> **For server/remote deployments only.** This mode requires the MCP server to be deployed with a publicly accessible HTTPS URL. For local/desktop use, see `GITLAB_USE_OAUTH` above.

For remote MCP clients that support the MCP OAuth specification (e.g. Claude.ai).
The server acts as a full OAuth 2.0 authorization server — unauthenticated requests
receive a `401 + WWW-Authenticate` response, which triggers the OAuth browser flow
automatically on the client side.

Remote MCP clients such as OpenCode, MCPJam, and Claude.ai can send their own
callback URL during authorization. If you cannot register every client callback
URL in GitLab, enable `GITLAB_OAUTH_CALLBACK_PROXY=true`. With callback proxy
mode, GitLab only needs one registered redirect URI: `{MCP_SERVER_URL}/callback`.

`GITLAB_OAUTH_REDIRECT_URI` is for local OAuth (`GITLAB_USE_OAUTH`) only. It does
not override remote MCP OAuth client callback URLs and should not be used to fix
remote `Unregistered redirect_uri` errors.

This variable exists because the local OAuth flow starts a browser on the same
machine as the MCP server and listens for the callback on a local HTTP server,
for example `http://127.0.0.1:8888/callback`.

Remote MCP OAuth is different. In `GITLAB_MCP_OAUTH=true` mode, the MCP client
provides its own callback URL during `/authorize`. `GITLAB_OAUTH_REDIRECT_URI`
does not replace that client-provided URL.

| Mode | Enable with | Callback variable | GitLab redirect URI |
| --- | --- | --- | --- |
| Local OAuth | `GITLAB_USE_OAUTH=true` | `GITLAB_OAUTH_REDIRECT_URI` | `http://127.0.0.1:8888/callback` or your local callback |
| Remote MCP OAuth | `GITLAB_MCP_OAUTH=true` | `GITLAB_OAUTH_CALLBACK_PROXY=true` | `{MCP_SERVER_URL}/callback` |

Use `GITLAB_OAUTH_REDIRECT_URI` only when the MCP server itself owns the local
browser callback. Use `GITLAB_OAUTH_CALLBACK_PROXY=true` when a remote MCP client
owns the callback URL.

**How it works**: You deploy this MCP server somewhere with a public HTTPS URL. MCP
clients connect to `{MCP_SERVER_URL}/mcp`. The server handles the OAuth 2.0 flow,
exchanging credentials with GitLab on behalf of the client.

**Prerequisites**:

1. A publicly accessible HTTPS server URL (`MCP_SERVER_URL`) — use [ngrok](https://ngrok.com) for local testing
2. A pre-registered GitLab OAuth application with `api` (or `read_api`) scopes
   — Go to `Admin area` → `Applications`, set Redirect URI to `{MCP_SERVER_URL}/callback`

| Environment Variable  | Required | Description                                                |
| --------------------- | -------- | ---------------------------------------------------------- |
| `GITLAB_MCP_OAUTH`    | ✅       | Set to `true` to enable                                    |
| `GITLAB_API_URL`      | ✅       | GitLab API base URL                                        |
| `GITLAB_OAUTH_APP_ID` | ✅       | GitLab OAuth Application ID                                |
| `MCP_SERVER_URL`      | ✅       | Public HTTPS URL of this MCP server                        |
| `STREAMABLE_HTTP`     | ✅       | Must be `true`                                             |
| `GITLAB_OAUTH_CALLBACK_PROXY` | optional | Set to `true` to use the MCP server's fixed `/callback` URL |
| `GITLAB_OAUTH_SCOPES` | optional | Comma-separated scopes (default: `api,read_api,read_user`) |
| `GITLAB_OAUTH_ALLOWED_GROUPS` | optional | Comma-separated group full paths — only members (and subgroup members) may obtain a token (replaces deprecated `GITLAB_ALLOWED_GROUPS`) |

When `STREAMABLE_HTTP=true`, server-side `GITLAB_PERSONAL_ACCESS_TOKEN` or `GITLAB_JOB_TOKEN` require `REMOTE_AUTHORIZATION=true` or `GITLAB_MCP_OAUTH=true`.

> **Troubleshooting `Unregistered redirect_uri`**
>
> Check the `redirect_uri` in the browser URL. If it points to a client callback
> such as `http://127.0.0.1:xxxxx/.../callback`, enable:
>
> ```env
> GITLAB_OAUTH_CALLBACK_PROXY=true
> ```
>
> Do not fix remote MCP OAuth by changing `GITLAB_OAUTH_REDIRECT_URI`. That
> variable is for local OAuth (`GITLAB_USE_OAUTH`) only.

```shell
docker run -i --rm \
  -e HOST=0.0.0.0 \
  -e GITLAB_MCP_