gitlab-mcp

gitlab-mcp

An MCP server for GitLab issues, merge requests, releases, and repository browsing.

It talks to the GitLab API directly rather than shelling out to the glab CLI. That is what lets every tool take a project argument: glab's own MCP server registers ~194 commands as tools and derives the project from the git remote of its working directory, because it hides the --repo flag from the tool schema (cmdutils.AddGlobalRepoOverride calls MarkHidden("repo")). This server needs no checkout, no glab binary, and exposes 20 tools instead.

Build

go build ./cmd/gitlab-mcp
# stdio transport (for Claude Code / Claude Desktop):
./gitlab-mcp
# HTTP transport with debug logging:
./gitlab-mcp -transport streamable-http -addr :8083 -log-file /tmp/gitlab-mcp.log

Configuration

If you already run glab auth login, no configuration is needed:

./gitlab-mcp                                  # uses glab's host and token
./gitlab-mcp -project mygroup/myproject       # ...and defaults every tool to one project

Without a token, only public projects are readable, and the server logs a warning at startup.

Authentication

-auth decides whose GitLab credential a session runs as.

Callers send their token on either header, PRIVATE-TOKEN taking precedence:

PRIVATE-TOKEN: glpat-xxxxxxxxxxxx
Authorization: Bearer glpat-xxxxxxxxxxxx

The credential is read once per MCP session, not per tool call, and clients presenting the same token share one GitLab client. Under -auth=client the server holds no credential of its own: the glab config is read only for the instance URL, and an explicit -gitlab-token is ignored with a warning.

Two guardrails refuse to start rather than fail quietly:

• client/client-optional require an HTTP transport. stdio has no headers, so a caller could never present a token and every session would silently read as anonymous.
• They require TLS, or an explicit -auth-insecure. Passthrough puts a credential on the wire.

The instance URL is always the operator's, in every mode. A server that let a caller supply both host and token would be a shared server; one that let a caller supply the host while the server supplies the token would be a credential-exfiltration endpoint. effect.AllowHostOf pins egress to the configured instance and nothing in a request can widen it.

Note what client mode is not: authentication of the caller to this server. GitLab validates the token on the first API call, so a session opened with a garbage token is accepted here and fails there. If you need the server itself to reject unknown callers, put it behind something that does that.

Because the credential is bound at session creation, the Mcp-Session-Id is as sensitive as the token itself: requests on an existing session run as whoever opened it, and a PRIVATE-TOKEN header sent later in that session is ignored rather than honoured. Isolation between users is therefore only as good as the secrecy of the session ID, which is another reason -auth-insecure is a deliberate opt-out.

Tools

Every tool takes project — a path like group/project, a nested path like group/sub/project, or a numeric ID. It is optional only when -project was given. repo_search finds the path when you do not know it. Issues and merge requests are addressed by their project-scoped number (#123, !123).

There is deliberately no mr_merge, no mr_approve, and nothing that deletes.

Labels on update

labels replaces the whole set; add_labels and remove_labels edit it. Sending labels when you meant to add one drops every other label.

Resources

The URIs mirror GitLab's own web URLs, /-/ included: a project path has an unbounded number of group segments, so something has to mark where it ends. The ref in a blob URI cannot contain a slash, so address a branch like feat/x by commit SHA. The tools have no such limit.

Response size

A single API response can dwarf everything else in an agent's context, so the tools cap what they return and say when they did: descriptions and READMEs at 20k runes, repo_file at 200k, mr_diff at 100k of total diff text. mr_diff keeps the file list complete even when it drops diff text — an agent that sees a name can ask for that file with repo_file; one that never saw it cannot. Lists default to 20 results per page and accept page/per_page.

Security

Per the effect-provider invariant in CLAUDE.md:

• Every request goes through an effect.NewHTTPClient whose egress allowlist is exactly the configured instance. A release asset link can point at any host — GitLab allows external links — so release_asset_download is the one place a tool follows a URL chosen by project content. The allowlist is what stops that from turning this server into a fetch-anything proxy.
• The release asset tools reach host files only through effect.Root(-assets-dir). With no -assets-dir they get an effect.Deny provider and can touch nothing. No handler checks paths itself.
• Reading glab's config uses os.ReadFile because it is an operator-controlled startup path that no agent can influence.
• Under -auth=server on an HTTP transport, the server is a shared-credential proxy: whoever reaches -addr acts as the token it started with. That is the default because it is what stdio needs; it is -auth=client that makes an exposed server safe to share.
• The per-token client cache is bounded at 128 entries and dropped wholesale past it, because under -auth=client the set of tokens is caller-supplied and so is attacker-driven input.