Gitlab Mcp

gitlab-mcp

[CI] [Release] [Go Reference] [License: Apache 2.0]

An MCP server for gitlab.com. One binary over stdio, signed in as you, with your own OAuth application and the token in your OS keyring.

It is for a person with a gitlab.com account who wants an assistant to find and read issues, review merge requests, follow CI and make the changes they ask for, as them. It works inside projects: issues, merge requests, reviews, the repository and CI. It does not administer an instance or a group, and it does not serve self-managed instances.

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

Goals and non-goals

Goals:

• Content never steers the assistant through the server. Issues, reviews, files and job logs come back marked as untrusted data, hidden text is counted, nothing they link to is fetched, and token shapes in CI output are masked.
• Nothing it writes runs a command. A quick action such as /merge in a comment is refused or escaped, never executed.
• Nothing ships, deletes or reaches further unless you turn it on. Merging, approving, running CI and deleting are not registered by default, code reaches a protected branch only through a merge request, and writes can be confined to the groups you name.
• A write changes only what you read and named. Writes carry what they read and are refused when it moved, a lost create is settled by reading, and every write takes dry_run.
• Reads are bounded. Every read has a budget and says what it left out and how to continue.
• Act as you, and log nothing about your work. Every call runs as the signed-in account, and the logs never carry paths, titles or bodies.

Non-goals:

• Self-managed instances. It talks to gitlab.com and nothing else.
• Administration. Instance and group settings, users, runners, access tokens, deploy keys, webhooks and integrations are out.
• CI variables and secure files. Reading them would put secrets in a model's context.
• Deleting projects or groups, force pushes and protected-branch settings, not even behind a switch.
• A raw API tool. Every call is a tool with its own guards; nothing sends an arbitrary REST or GraphQL request.
• Events pushed to it. Webhooks need a listener, and a stdio process has none.
• A hosted service. It speaks stdio only, so Claude on the web and on mobile cannot reach it.
• Asking you before a call. Your client approves each call; the server asks nothing.

What makes this one different

• A curated surface, gated by registration. A tool for each thing a person does in a project, 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. GitLab runs /merge and the rest from any comment or description sent through its API.
• Content is marked as untrusted. Issues, reviews, files and job logs come back inside boundaries the content cannot close.
• Reviews the way people review. Draft comments, published together, and the server, not the model, computes where an inline comment lands.
• Signs in like a desktop app. Your own OAuth application, a browser tab, the token in the OS keyring. GitLab's own MCP server runs on the instance over HTTP, and a stdio client reaches it through a Node.js proxy.
• Verifiable releases. Signed checksums, build provenance and SBOMs.

Tools

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

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

   bash

   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:

   bash

   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. It asks for the same settings: merging, approving, rebasing, applying suggestions, moving issues, CI and releases (enable_ship) and deleting (enable_destructive) stay off unless you turn them on, and write_namespaces confines writes to the groups and projects you name. This server asks nobody before a call. Claude Desktop approves each tool, and a tool you always allow then runs unasked, so leave a switch off unless you need its tools.

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:

Your MCP client approves each call; the server does not ask you itself. claude.ai, Claude Desktop and Codex prompt for every tool marked destructive: every write but the ones that only add, such as create_issue and create_label. VS Code prompts for every tool that writes. In Claude Code, delete_label, delete_milestone and make_issue_public ask on every call whatever your rules say, since none can be undone and each reaches past the one item: a label or milestone comes off every issue and merge request, and a public issue is read by everyone. For the rest, list the calls you want to approve one by one under permissions.ask in your settings, with the name you gave the server in place of gitlab. For example, the writes that ship, publish, upload or delete:

{  "permissions": {    "ask": [      "mcp__gitlab__merge_merge_request", "mcp__gitlab__approve_merge_request",      "mcp__gitlab__apply_suggestions", "mcp__gitlab__run_pipeline",      "mcp__gitlab__run_merge_request_pipeline", "mcp__gitlab__play_job",      "mcp__gitlab__create_release", "mcp__gitlab__create_tag", "mcp__gitlab__move_issue",      "mcp__gitlab__upload_file",      "mcp__gitlab__delete_branch", "mcp__gitlab__delete_comment",      "mcp__gitlab__delete_wiki_page", "mcp__gitlab__delete_label",      "mcp__gitlab__delete_milestone", "mcp__gitlab__delete_tag",      "mcp__gitlab__delete_snippet"    ]  }}

• 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.
• Local files only from where you allow. upload_file reads an image only from the directories GITLAB_MCP_UPLOAD_DIRS names, and only a PNG, JPEG, GIF or WebP judged from its bytes, so a comment asking for a key file to be "attached" gets nothing.

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-missingcosign 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.comgh attestation verify <archive> --repo mmedum/gitlab-mcp

Getting help

Run gitlab-mcp doctor first: it checks the connection, the sign-in, the application and the granted scopes, and names what is missing. docs/troubleshooting.md covers each failure. Then open an issue with doctor's output and the version. Do not paste a tool result: it is your organization's code and other people's words.

Documentation

• docs/setup.md: registering the OAuth application and logging in.
• docs/configuration.md: every setting, what each registers, and where state is stored.
• docs/troubleshooting.md: symptoms and their fixes, then rotating the token, revoking access and handling a suspected exposure.
• docs/security.md: the threat model.
• docs/architecture.md: how it works, and the design decisions a contributor should not undo.
• docs/release.md: how a release is cut and checked.
• CHANGELOG.md: what each release changed. The tool names and their output fields are the contract, and anything you have to act on is marked Breaking.

Contributing

CONTRIBUTING.md covers the gates, the live run and the review flow. Security reports go through SECURITY.md, not an issue.

License

Apache-2.0. See LICENSE and NOTICE.