Gitlab MCP Server

gitlab-mcp

An MCP server for gitlab.com. One binary over stdio, signed in as you. It works inside projects: issues, merge requests, reviews, the repository and CI. Instance and group administration, runners, CI variables and tokens are out of scope.

Unofficial, and not affiliated with GitLab Inc. See NOTICE.

What makes this one different

• A small surface, gated by registration. About sixty tools rather than an API mirror, and a tool that is switched off is not registered, so it cannot be called at all.
• Nothing it writes runs a quick action. /merge in a comment is refused or escaped, never executed.
• Content is marked as untrusted. Issues, reviews, files and job logs come back inside boundaries the content cannot close.
• Signs in like a desktop app. Your own OAuth application, a browser tab, the token in the OS keyring.
• Verifiable releases. Signed checksums, build provenance and SBOMs.

Status

Stable: the release badge above names the newest tag, and CHANGELOG.md says what each one holds. The tool surface is a contract: tools keep their names and output fields. docs/architecture.md §16 is the plan.

Tools

Ship and Destructive tools are registered only with the settings below, and the six toolsets only when GITLAB_MCP_TOOLSETS names them.

Three resources carry the same text for clients that attach rather than call: an issue, a merge request and a job log.

Install

Download an archive for your platform from the releases page, or:

go install github.com/mmedum/gitlab-mcp/v2/cmd/gitlab-mcp@latest

Claude Desktop users can open the .mcpb bundle from the same release. It does not log you in; do the steps below first.

Sign in

You bring your own OAuth application. Nothing is shipped in the binary, and there are no personal access tokens.

1. Register an application, once. On gitlab.com: your avatar → Edit profile → Applications (or a group's). Redirect URI http://127.0.0.1/callback, Confidential unchecked, scope api (read_api for read-only). docs/setup.md has the exact values.

2. Log in from a terminal:

   gitlab-mcp login --client-id <application id>
   

   It prints the scopes it will ask for, opens your browser, and stores the token in the OS keyring. On a machine without a browser, --no-browser prints the URL and the ssh -L line to forward the callback.

3. Check it:

   gitlab-mcp doctor
   

   doctor walks the connection, TLS, the sign-in, the application, the granted scopes and one call as you, and names what is missing. status and logout do what they say; --profile keeps two gitlab.com logins side by side.

Connect a client

Claude Code:

claude mcp add gitlab -- gitlab-mcp

Any client that takes a JSON server list:

{
  "mcpServers": {
    "gitlab": { "command": "gitlab-mcp" }
  }
}

Claude Desktop can instead open the .mcpb bundle from a release.

Configuration

Every setting is an environment variable with the GITLAB_MCP_ prefix and a matching flag. docs/configuration.md lists them all.

Safety

GitLab content was written by someone other than you, and some of it is written to steer an agent. The server marks it as untrusted data, never fetches what it references, and nothing it adds tells the model to act on it.

What can be registered depends on the settings, because GitLab's api scope cannot separate any of it:

When your MCP client supports elicitation, the server also asks you before it merges, approves, runs a manual job or a pipeline on a protected ref, publishes a release or a tag, makes a confidential issue public, or deletes anything. Only your accept writes.

• No quick actions. GitLab runs /merge, /close and the rest from a description or comment. Every body this server sends is checked, and a quick-action line is refused, or escaped when you ask.
• Protected branches. Code reaches the default branch or a protected branch only through a merge request; a direct commit there is refused.
• No blind retries. A create that may or may not have happened is settled by reading, never by creating again.

The default token can still merge and approve; leaving Ship off stops this server doing so, not anything else holding the token. docs/security.md says more.

Verify a release

Each release signs checksums.txt with a keyless Sigstore certificate and attests every archive and the bundle:

sha256sum -c checksums.txt --ignore-missing
cosign verify-blob checksums.txt --bundle checksums.txt.bundle \
  --certificate-identity "https://github.com/mmedum/gitlab-mcp/.github/workflows/release.yml@refs/tags/<tag>" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
gh attestation verify <archive> --repo mmedum/gitlab-mcp

Contributing

CONTRIBUTING.md. Security reports go through SECURITY.md, not an issue.

License

Apache-2.0. See LICENSE and NOTICE.