mcp-gitlab

# mcp-gitlab

[![PyPI version](https://img.shields.io/pypi/v/mcp-gitlab)](https://pypi.org/project/mcp-gitlab/)
[![PyPI downloads](https://img.shields.io/pypi/dm/mcp-gitlab)](https://pypi.org/project/mcp-gitlab/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-gitlab)](https://pypi.org/project/mcp-gitlab/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/vish288/mcp-gitlab/actions/workflows/tests.yml/badge.svg)](https://github.com/vish288/mcp-gitlab/actions/workflows/tests.yml)
[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io)

<!-- mcp-name: io.github.vish288/mcp-gitlab -->

**mcp-gitlab** is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for the GitLab REST API. It gives AI assistants **91 tools**, **7 resources**, and **6 prompts** to manage projects, merge requests, pipelines, CI/CD variables, approvals, issues, and code reviews. Works with Claude Desktop, Claude Code, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible client.

Supports GitLab.com and self-hosted GitLab instances (CE/EE). No GitLab Duo or Premium required.

Supports the MCP 2026-07-28 specification, often called MCP 2.0, and stays compatible with 2025-11-25 clients.

Built with [FastMCP](https://github.com/jlowin/fastmcp) 4.x, [httpx](https://www.python-httpx.org/), and [Pydantic](https://docs.pydantic.dev/).

**Install:** `uvx mcp-gitlab` | [PyPI](https://pypi.org/project/mcp-gitlab/) | [MCP Registry](https://registry.modelcontextprotocol.io) | [Changelog](https://github.com/vish288/mcp-gitlab/releases)

## 1-Click Installation

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://vish288.github.io/mcp-install?server=mcp-gitlab&install=cursor)

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vish288.github.io/mcp-install?server=mcp-gitlab&install=vscode) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vish288.github.io/mcp-install?server=mcp-gitlab&install=vscode-insiders)

> **💡 Tip:** For other AI assistants (Claude Code, Windsurf, IntelliJ, Gemini CLI), visit the **[GitLab MCP Installation Gateway](https://vish288.github.io/mcp-install?server=mcp-gitlab)**.

<details>
<summary><b>Manual Setup Guides (Click to expand)</b></summary>
<br/>

> Prerequisite: Install `uv` first (required for all `uvx` install flows). [Install uv](https://docs.astral.sh/uv/getting-started/installation/).

### Claude Code

```bash
claude mcp add gitlab -- uvx mcp-gitlab
```

### Windsurf & IntelliJ

**Windsurf:** Add to `~/.codeium/windsurf/mcp_config.json`
**IntelliJ:** Add to `Settings | Tools | MCP Servers`

> **Note:** The actual server config starts at `gitlab` inside the `mcpServers` object.

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "uvx",
      "args": ["mcp-gitlab"],
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

### Gemini CLI

```bash
gemini mcp add -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx gitlab uvx mcp-gitlab
```

### pip / uv

```bash
uv pip install mcp-gitlab
```

</details>

## Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GITLAB_URL` | **Yes** | - | GitLab instance URL (e.g. `https://gitlab.example.com`) |
| `GITLAB_TOKEN` | Yes, unless signed in with `mcp-gitlab auth login` | - | Authentication token (see below) |
| `GITLAB_READ_ONLY` | No | `false` | Set to `true` to disable write operations |
| `GITLAB_TIMEOUT` | No | `30` | Request timeout in seconds |
| `GITLAB_SSL_VERIFY` | No | `true` | Set to `false` to skip SSL verification |
| `GITLAB_AUTH` | No | `token` | `token` (PAT from env) or `oauth` (OAuth 2.1 proxy; see below) |

### Supported Token Types

The server checks these environment variables in order — first match wins:

1. `GITLAB_TOKEN`
2. `GITLAB_PAT`
3. `GITLAB_PERSONAL_ACCESS_TOKEN`
4. `GITLAB_API_TOKEN`

These accept any of the following token types:

| Token Type | Format | Use Case |
|------------|--------|----------|
| Personal access token | `glpat-xxx` | User-level access with `api` scope |
| OAuth2 token | `oauth-xxx` | OAuth app integrations |
| CI job token | `$CI_JOB_TOKEN` | GitLab CI pipeline access |

## Sign in without a token

Use this when you run the server for yourself over `stdio` and have no personal
access token. `mcp-gitlab auth login` signs you in to GitLab as a public OAuth
client and stores the tokens locally. The server then reads them at startup and
refreshes them on its own. This is not OAuth mode; the server stays in token
mode and nothing on the MCP wire changes.

Three commands:

```bash
mcp-gitlab auth login     # device flow by default; add --web for the browser flow
mcp-gitlab auth status    # show the stored account, scopes, and token freshness
mcp-gitlab auth logout    # revoke the token at GitLab and delete the local copy
```

`auth login` prints a code and a URL. Open the URL, enter the code, and approve.
The server then works with `GITLAB_URL` set and no token.

### Client ID

Each sign-in needs an OAuth application ID. Resolution order: `--client-id`,
then `GITLAB_OAUTH_CLIENT_ID`, then a built-in default for `https://gitlab.com`.

The gitlab.com default is not registered yet. Until it is, set
`GITLAB_OAUTH_CLIENT_ID` or pass `--client-id` for gitlab.com too.

### Register an app (self-managed, or gitlab.com until the default ships)

Create an application under **User Settings → Applications → Add new
application** with these settings:

| Field | Value |
|-------|-------|
| Name | `mcp-gitlab` |
| Redirect URI | `http://127.0.0.1/callback` (loopback IP, no port) |
| Confidential | unchecked (public client) |
| Scopes | `api`, `read_api` |

Use `127.0.0.1`, not `localhost`. The device flow needs GitLab 17.9 or later; on
older instances use `mcp-gitlab auth login --web`.

### Storage and precedence

Credentials live in `~/.config/mcp-gitlab/credentials.json`, one entry per
GitLab URL, mode 0600. An environment token always wins: if `GITLAB_TOKEN` is
set, the server uses it and ignores the stored credentials.

Pass `--scopes read_api` for a read-only session; the server then blocks write
tools before any API call.

## OAuth 2.1 (remote deployments)

For a server shared by several people, `--auth oauth` turns mcp-gitlab into an
MCP 2026-07-28 resource server with GitLab as the upstream OAuth provider: each
user signs in with their own GitLab account, every request runs with that
user's token, and no personal access token is configured on the server. Use it
when you host the server once and multiple users connect to it; keep the
default `--auth token` for a single-user local setup.

OAuth mode requires `--transport streamable-http` (OAuth applies to HTTP only;
stdio keeps using the environment token).

**1. Register a GitLab OAuth application** (User Settings → Applications, or a
group/instance application). Set the redirect URI to `<base>/auth/callback`
(e.g. `https://mcp.example.com/auth/callback`), mark it confidential, and grant
the `api` scope (or `read_api` for a read-only deployment). Copy the
Application ID and Secret.

**2. Configure the server:**

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GITLAB_URL` | **Yes** | - | GitLab instance; also the upstream authorization server |
| `GITLAB_OAUTH_CLIENT_ID` | **Yes** | - | Application ID (oauth mode, or local sign-in) |
| `GITLAB_OAUTH_CLIENT_SECRET` | **Yes** | - | Its secret |
| `GITLAB_OAUTH_BASE_URL` | **Yes** | - | Public URL of this server, no trailing slash (e.g. `https://mcp.example.com`). Resource URL is `<base>/mcp` |
| `GITLAB_OAUTH_SCOPES` | No | `api` | Space-separated GitLab scopes required on every request. Use `read_api` for a read-only deployment |
| `GITLAB_OAUTH_JWT_KEY` | No | derived | FastMCP JWT signing key, ≥ 32 random chars. Set it in production so client registrations survive a client-secret rotation |
| `FASTMCP_HOME` | No | platform data dir | The encrypted token store lives at `$FASTMCP_HOME/oauth-proxy/<fingerprint>/` |

```bash
GITLAB_URL=https://gitlab.com GITLAB_AUTH=oauth \
  GITLAB_OAUTH_CLIENT_ID=... GITLAB_OAUTH_CLIENT_SECRET=... \
  GITLAB_OAUTH_BASE_URL=https://mcp.example.com \
  uvx mcp-gitlab --transport streamable-http
```

Point an MCP client (or the MCP Inspector, `pnpm dlx @modelcontextprotocol/inspector`)
at `<base>/mcp`; it discovers the authorization server, runs the OAuth flow, and
each tool call then uses that user's GitLab token. A `read_api`-only token can
read but is refused writes with an actionable hint.

Full guide, client setup and troubleshooting: [docs/oauth.md](docs/oauth.md).

## Compatibility

| Client | Supported | Install Method |
|--------|-----------|----------------|
| Claude Desktop | Yes | `claude_desktop_config.json` |
| Claude Code | Yes | `claude mcp add` |
| Cursor | Yes | One-click deeplink or `.cursor/mcp.json` |
| VS Code Copilot | Yes | One-click deeplink or `.vscode/mcp.json` |
| Windsurf | Yes | `~/.codeium/windsurf/mcp_config.json` |
| Any MCP client | Yes | stdio or HTTP transport |

## Protocol support

mcp-gitlab implements the Model Context Protocol. It supports the 2026-07-28 specification, often called MCP 2.0. It stays compatible with 2025-11-25 clients.

- **Specification**: MCP 2026-07-28 (MCP 2.0). Verified over `stdio` and `streamable-http`.
- **Legacy clients**: 2025-11-25 clients still work.
- **Built on**: FastMCP 4.x and the MCP Python SDK 2.x.
- **Transports**: `stdio` (default) and `streamable-http` (recommended for remote). The `sse` (HTTP+S