GitLab

mcp-gitlab

mcp-gitlab is a Model Context Protocol (MCP) 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. Runs in one of two modes: with writes, or locked read-only (MCP_READ_ONLY=true) so the 57 write tools are never offered to the model.

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 4.x, httpx, and Pydantic.

Install: uvx mcp-gitlab | PyPI | MCP Registry | Changelog

uvx mcp-gitlab                          # with writes

MCP_READ_ONLY=true uvx mcp-gitlab # locked read-only: write tools are not listed

1-Click Installation

💡 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).

Manual Setup Guides (Click to expand)

Prerequisite: Install uv first (required for all uvx install flows). Install uv.

Claude Code

# with writes

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

locked read-only

claude mcp add gitlab -e MCP_READ_ONLY=true -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx -- 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. Remove MCP_READ_ONLY to allow writes.

{

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

Gemini CLI

# with writes

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

locked read-only

gemini mcp add -s user -e MCP_READ_ONLY=true -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx gitlab uvx mcp-gitlab

VS Code

Add to .vscode/mcp.json. Remove MCP_READ_ONLY to allow writes.

{

"servers": { "gitlab": { "type": "stdio", "command": "uvx", "args": ["mcp-gitlab"], "env": { "GITLAB_URL": "https://gitlab.example.com", "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx", "MCP_READ_ONLY": "true" } } } }

Codex

# with writes

codex mcp add gitlab --env GITLAB_URL=https://gitlab.example.com --env GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx -- uvx mcp-gitlab

locked read-only

codex mcp add gitlab --env MCP_READ_ONLY=true --env GITLAB_URL=https://gitlab.example.com --env GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx -- uvx mcp-gitlab

pip / uv

uv pip install mcp-gitlab

Drop MCP_READ_ONLY to allow writes. On a shared or hosted server put it in the deployer's env, not the client config.

Configuration

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:

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:

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:

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 /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:

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 /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.

Compatibility

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.

• **Speci