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.

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.

• 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+SSE) transport still works, but the 2026-07-28 specification deprecates it. The server prints a warning when you use it.
• Capabilities: tools, resources, and prompts. The server uses no roots, sampling, logging, elicitation, or resource subscriptions, so the 2026-07-28 deprecations do not affect it.

Error results

An expected failure (a 404, a 401, a validation error, or a write that reaches the read-only guard) comes back as a tool result with the protocol-level isError flag set, so a client can detect and self-correct instead of parsing an "error" key out of an otherwise successful result. In locked read-only mode the write tools are hidden, so calling one returns an Unknown tool error; the read-only envelope is the guard’s own response, returned only when a client reaches a write tool anyway (a cached listing, or a future untagged tool). The body is a JSON object with error and, where it helps, status_code, body, and an actionable hint. That object is the result’s text content; the error sets no structuredContent, because a strict client (the TypeScript MCP SDK) validates structuredContent against the tool’s output schema even on an isError result and the schema would reject the error body. An unexpected bug is also an isError result but carries only TypeName: message text, likewise with no structuredContent.

A successful result carries the response as a JSON object in both the pretty text content and structuredContent (the object itself, not the old {"result": ""} wrapper a strict client would otherwise reject). Tools advertise no outputSchema: upstream GitLab fields pass through untyped, so a new API field never breaks a schema; a typed schema is opt-in per tool via output_schema= when a client needs one.

Tools (91)

Resources (7)

The server exposes curated workflow guides as MCP resources that clients can read on demand.

Prompts (6)

The server provides MCP prompts — reusable multi-tool workflow templates that clients can surface as slash commands.

Usage Examples

Projects & Branches

"Get details for project my-org/api-gateway"
→ gitlab_get_project(project_id="my-org/api-gateway")

"Create a feature branch from main"
→ gitlab_create_branch(project_id="123", branch_name="feat/login", ref="main")

"Delete all branches merged into main"
→ gitlab_list_branches(project_id="123") → filter merged → gitlab_delete_branch for each

Merge Requests & Code Review

"Open a merge request from feat/login to main"
→ gitlab_create_mr(project_id="123", source_branch="feat/login", target_branch="main", title="Add login")

"Review MR !42 — list changes and add inline comments"
→ gitlab_mr_changes(project_id="123", mr_iid=42)
→ gitlab_create_mr_discussion(project_id="123", mr_iid=42, body="nit: ...", new_path="src/auth.py", new_line=15)
  # old_line is filled from the diff when line 15 is unchanged

"Merge MR !42 after resolving all threads"
→ gitlab_list_mr_discussions(project_id="123", mr_iid=42) → resolve unresolved
→ gitlab_merge_mr(project_id="123", mr_iid=42, squash=True)

Pipelines & CI/CD

"Show failed pipelines on main this week"
→ gitlab_list_pipelines(project_id="123", ref="main", status="failed")

"Retry a failed pipeline"
→ gitlab_retry_pipeline(project_id="123", pipeline_id=456)

"Get the build log for job 789"
→ gitlab_get_job_log(project_id="123", job_id=789, tail_lines=100)

Issues

"Create a bug report in project 123"
→ gitlab_create_issue(project_id="123", title="Login page 500 error", labels=["bug","P1"])

"Find open issues assigned to me"
→ gitlab_list_issues(project_id="123", state="opened", assignee_username="johndoe")

Security Considerations

• Token scope: Use the minimum required scope. api scope grants full access; prefer read_api for read-only deployments.
• Read-only mode: Set MCP_READ_ONLY=true (or GITLAB_READ_ONLY=true) in the launch you control and the server starts locked: the 57 write tools and the write-workflow prompts are not listed, a call to one returns “Unknown tool”, and the guard refuses any write that still reaches it. Nothing lifts the lock at runtime — not a false from another source, not a .env file, not tool arguments; any value other than false/0/no/off/empty locks, and --read-only can only raise it. The lock is only as strong as the launch: set it where users cannot edit it (a managed MCP config such as Claude Code managed-mcp.json, a container, k8s or systemd env, or a hosted HTTP deployment). A user who starts the server themselves controls its environment. In OAuth mode also set GITLAB_OAUTH_SCOPES=read_api so each user’s GitLab token lacks write scope.
• SSL verification: GITLAB_SSL_VERIFY=true by default. Only disable for self-signed certificates in trusted networks.
• CI/CD variable masking: gitlab_list_variables and gitlab_list_group_variables automatically mask values of variables marked as masked in GitLab, returning ***MASKED*** instead of the actual value.
• MCP tool annotations: Each tool declares readOnlyHint, destructiveHint, and idempotentHint for client-side permission prompts.
• Credential storage: The server reads GITLAB_TOKEN from the environment and never writes it. mcp-gitlab auth login stores OAuth tokens in ~/.config/mcp-gitlab/credentials.json (mode 0600) and refreshes them in place.

Rate Limits & Permissions

Rate Limits

GitLab enforces per-user rate limits (default: 2000 requests/minute for authenticated users). When rate-limited, tools return a 429 error with a hint to wait before retrying. Paginated endpoints default to 20 results per page; use per_page (max 100) to reduce the number of API calls.

Required Permissions

CLI & Transport Options

# Default: stdio transport (for MCP clients)
uvx mcp-gitlab

# HTTP transport — streamable-http is recommended for remote use
uvx mcp-gitlab --transport streamable-http --port 9000

# SSE transport — deprecated by MCP 2026-07-28; still works, prints a warning
uvx mcp-gitlab --transport sse --host 127.0.0.1 --port 8000

# OAuth 2.1 mode (per-user GitLab sign-in; streamable-http only) — see "OAuth 2.1" above
uvx mcp-gitlab --auth oauth --transport streamable-http

# Local sign-in for stdio without a token — see "Sign in without a token" above
mcp-gitlab auth login|status|logout

# CLI overrides for config
GITLAB_TOKEN=glpat-xxx uvx mcp-gitlab --gitlab-url https://gitlab.example.com --read-only

--gitlab-token still works but is deprecated and hidden from --help: it exposes the token to ps and shell history. Use GITLAB_TOKEN.

--auth {token,oauth} selects the authentication mode (token by default); oauth requires --transport streamable-http.

In token mode an HTTP transport serves every tool with the single GITLAB_TOKEN to anyone who reaches the port, so binding to a non-loopback --host is refused unless you set GITLAB_HTTP_BEARER_TOKEN (≥ 16 chars; clients send it as Authorization: Bearer ) or switch to --auth oauth for per-user sign-in. The default 127.0.0.1 bind needs neither.

The server loads .env files from the working directory automatically via python-dotenv.

Docker

A minimal non-root image builds straight from this repo (uv, the committed uv.lock). The image defaults to locked read-only (MCP_READ_ONLY=true); override it to allow writes.

docker build -t mcp-gitlab .

# locked read-only (the image default) — stdio for an MCP client
docker run --rm -i \
  -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx \
  mcp-gitlab

# allow writes: override the read-only default
docker run --rm -i \
  -e MCP_READ_ONLY=false \
  -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx \
  mcp-gitlab

For an HTTP transport, append --transport streamable-http --host 0.0.0.0; a non-loopback bind in token mode needs GITLAB_HTTP_BEARER_TOKEN (≥ 16 chars) or GITLAB_AUTH=oauth (see above).

FAQ

Does mcp-gitlab support MCP 2.0?

Yes. It supports the MCP 2026-07-28 specification, often called MCP 2.0. It also stays compatible with 2025-11-25 clients.

Does it work with self-hosted GitLab?

Yes. It works with GitLab.com and self-hosted GitLab (CE and EE). It needs no GitLab Duo or Premium.

Which transports does it support?

It supports stdio (the default) and streamable-http. The sse transport still works, but the 2026-07-28 specification deprecates it. OAuth 2.1 mode (--auth oauth) is available on streamable-http only.

Can I run mcp-gitlab read-only so the assistant cannot merge, push or comment?

Yes. Start it with MCP_READ_ONLY=true (or GITLAB_READ_ONLY=true). The 57 write tools and the write-workflow prompts are then not listed at all, so the model never sees them; a call to one returns “Unknown tool”, and nothing can turn writes back on while the process runs. Set it in a launch you control — a managed MCP config, a container or systemd env, or a hosted deployment — because a user who starts the server themselves can start it without the variable.

What token scopes does it need?

Use a token with the api scope for full access. Use the read_api scope for read-only deployments. The server reads a GITLAB_TOKEN from the environment and never writes it; tokens from mcp-gitlab auth login are stored in ~/.config/mcp-gitlab/credentials.json.

Which AI assistants work with it?

It works with Claude Desktop, Claude Code, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible client.

How do I install mcp-gitlab?

Run uvx mcp-gitlab, or add it to your MCP client configuration. See the installation section above.

Related MCP Servers

• mcp-atlassian-extended — Jira + Confluence integration (22 tools, 15 resources, 5 prompts)
• mcp-coda — Coda integration (53 tools, 12 resources, 5 prompts)
• mcp-argocd — Argo CD integration (37 tools, 7 resources, 7 prompts)

Development

git clone https://github.com/vish288/mcp-gitlab.git
cd mcp-gitlab
uv sync --all-extras

uv run pytest --cov
uv run ruff check .
uv run ruff format --check .

License

MIT