PlugWiki
GitLab MCP Server logo

Add the GitLab MCP server to Claude Code

Add GitLab to Claude Code with one command, then sign in through /mcp. Use -s user so it works in every project.

Run one command in your terminal to add GitLab to Claude Code, then type /mcp and approve the sign-in in your browser. Keep the -s user part of the command, or GitLab will load in only one folder. Before any of this works, a group Owner on GitLab.com or an admin on Self-Managed must allow MCP access.

If the connection drops mid-session, as it sometimes does, reconnect from /mcp.

Good for

  • Developers who want Claude Code to review merge requests and read issues without leaving the terminal
  • Engineers who ask Claude Code why a pipeline failed
  • Self-Managed and Dedicated users who need their own GitLab host, not gitlab.com
  • Group Owners and admins who must switch MCP access on first

Add GitLab to Claude Code

Claude Code

  1. 1

    Copy this prompt.

    Add the GitLab MCP server to Claude Code. Run this command:

claude mcp add -s user --transport http GitLab https://gitlab.com/api/v4/mcp

Then check that it loaded and tell me if I need to sign in or restart.
  2. 2

    Paste it into Claude Code. It shows the change and asks before running it.

Requires MCP access allowed by your group Owner or instance admin.

Read-only mode: No read-only setting exists. Load fewer tool groups with the toolsets option, and add deny rules for write tools in your Claude Code permission settings.

Run the add command in your terminal, not inside a claude session. Then start claude, type /mcp, pick GitLab and approve the request in your browser. Run /mcp again to check it shows as connected.

On Self-Managed or Dedicated, replace gitlab.com with your own host. Keep -s user: without it GitLab loads only in the folder where you ran the command, and that local entry beats a user one with the same name.

Pick the second method only on GitLab 19.5 or later. A misspelled group name makes GitLab answer 400. The first method already works with Claude Code's default tool loading.

From the vendor's docs. Source.

Common errors and fixes

  • Every GitLab call fails with 403 right after sign-in

    Cause: MCP access is not allowed for your top-level group (GitLab.com) or your instance (Self-Managed, Dedicated).

    Fix: Ask a group Owner or instance admin to allow MCP access. On GitLab 19.4 and earlier the same cause shows as 404.

    claude-code Source

  • GitLab is missing in other folders, or the old settings keep winning

    Cause: The server was added at local scope without -s user. A local entry beats a user entry with the same name, and claude mcp add will not overwrite it.

    Fix: Run claude mcp list, then claude mcp remove GitLab -s local, then add it again with -s user.

    claude-code Source

  • Connection closed, then every GitLab call fails until you restart

    Cause: The connection can drop mid-session and not recover.

    Fix: Open /mcp and pick Reconnect on GitLab, or run /mcp reconnect all. Restart Claude Code if that fails.

    claude-code Source

  • Generic connection error after many GitLab requests

    Cause: Over the rate limit GitLab returns a plain-text 429 that Claude Code may show as a connection error. The allowance is shared with your other MCP apps.

    Fix: Wait for the Retry-After time, then try again. GitLab.com allows 60 requests a minute on Free and 600 on Premium and Ultimate.

    claude-code Source

  • CI job logs or file contents come back empty or saved to a file

    Cause: Claude Code caps MCP results at 25,000 tokens and saves text over 50,000 characters to a file. It can also keep only the structured part of a result.

    Fix: Ask Claude to read the saved file, or ask for a smaller slice such as the last lines of the log. Raise MAX_MCP_OUTPUT_TOKENS for the token cap.

    claude-code Source

  • GitLab plugin connects but shows no tools, or never reaches your Self-Managed host

    Cause: The marketplace plugin hardcodes gitlab.com and its sign-in can fail and leave the server with no tools.

    Fix: Remove the plugin and add GitLab with the command in the install box, using your own host.

    claude-code Source

  • Creating a merge request fails with a validation error

    Cause: GitLab's tool and server disagree about the request, and the fix is still open.

    Fix: Open the merge request with git push options: git push -o merge_request.create -o merge_request.target=<branch>.

    claude-code Source

Permissions

Medium risk

In Claude Code, GitLab acts as you, so an auto-approve rule lets it create merge requests or run pipelines without asking. Keep write tools on ask and allow only the read tools you use.

What it can do

  • Read your data
  • Create and change things
  • Delete things
  • Read-only mode

Watch out for

  • Auto-approve modes let it change GitLab unasked

    An allow rule like mcp__GitLab__* or bypassPermissions mode lets Claude create merge requests or run pipelines without a prompt. Allow read tools by name and leave write tools on ask. code.claude.com

  • Text in issues and MRs can steer Claude

    GitLab says you are responsible for guarding against prompt injection in Claude Code too. Use it only on GitLab items you trust. docs.gitlab.com

  • Removing the server does not revoke its token

    claude mcp remove deletes the local token but leaves it valid at GitLab. Run claude mcp logout GitLab first. code.claude.com

  • GitLab does not yet flag destructive tools

    GitLab has open work to mark tools that overwrite or remove data, so Claude Code cannot tell them apart from safe edits in its approval prompts. gitlab.com

Security advisories

Technical details
Turning on read-onlyNo read-only switch. In Claude Code, load fewer tools with the X-Gitlab-Enabled-Mcp-Server-Toolsets header and add deny rules such as mcp__GitLab__<tool> for write tools in your permission settings.
Scopes

  • mcp

Works in

Claude Code is a documented GitLab client, with a few open problems around dropped connections and large results.

Tap an app to see how to set it up and any known problems.

Questions

Why does GitLab only work in one folder of Claude Code?

It was added without -s user, so it sits at local scope and loads only where you ran the command. Run claude mcp remove GitLab -s local, then add it again with -s user.

Why do I get 403 or 404 after signing in?

MCP access is not switched on for you. On GitLab.com a group Owner turns it on for the top-level group, and on Self-Managed an admin turns it on for the instance. GitLab 19.4 and earlier answer 404 for the same cause.

Sign-in fails with "The requested scope is invalid". What now?

Update Claude Code and sign in again from /mcp. Older builds asked for every scope GitLab lists instead of just the one it needs, and that is fixed.

GitLab stopped working halfway through a session. How do I fix it?

Open /mcp and pick Reconnect on GitLab, or run /mcp reconnect all on Claude Code v2.1.284 or later. If it asks you to sign in, pick Re-authenticate. GitLab is still investigating mid-session drops.

Can I sign in over SSH or in a script?

Yes, but sign in first. Run claude mcp login GitLab, which prints a URL over SSH (connect with ssh -t for the paste step). Runs with claude -p and the Agent SDK cannot open the browser sign-in themselves.

How do I make GitLab read-only in Claude Code?

You cannot switch it to read-only. Load fewer tool groups with the toolsets option in the install box, and add deny rules for write tools in your Claude Code permission settings.

Can I use a personal access token instead of the browser sign-in?

Only a fine-grained token with the MCP tool resource and Execute permission. Legacy, project and group tokens get 403. GitLab does not document the Claude Code command for it, and Claude Code will not fall back to browser sign-in if the token is rejected.

Should I use the GitLab plugin or the add command?

Use the add command in the install box. The plugin from Anthropic's marketplace points only at gitlab.com, so it cannot reach Self-Managed hosts, and users report sign-in failures with it. If both point at the same address, Claude Code uses your own entry.

Why are big job logs or files saved to a file instead of shown?

Claude Code warns above 10,000 tokens and caps MCP results at 25,000 by default. Text over 50,000 characters is saved to a file that Claude reads when needed. Raising MAX_MCP_OUTPUT_TOKENS lifts the token cap only.

How do I remove GitLab from Claude Code?

Run claude mcp logout GitLab first, then claude mcp remove GitLab. Removing alone deletes the local token but leaves it valid at GitLab. If it was added at local scope, add -s local to the remove command.

Information

updated Nov 1, 2026

GitLab MCP server docsOfficial MCP RegistryFeedback issueTroubleshooting

More on this

Sources

Docs, issue trackers and discussions this page is built from.

Show all 15
  1. GitLab MCP server · docs.gitlab.com
  2. Connect Claude Code to tools via MCP · code.claude.com
  3. GitLab MCP server troubleshooting · docs.gitlab.com
  4. Investigate: GitLab MCP server connection drops mid-session in Claude Code and doesn't recover · gitlab.com
  5. claude-plugins-official: gitlab plugin · github.com
  6. GitLab plugin: support configurable base URL for self-hosted instances · github.com
  7. MCP server at /api/v4/mcp: OAuth flow state lost between authenticate and complete_authentication · gitlab.com
  8. GitLab MCP: create merge request validation mismatch · gitlab.com
  9. Claude Code: CI job logs empty · github.com
  10. Claude Code permissions · code.claude.com
  11. MCP: mark destructive tools · gitlab.com
  12. GitLab patch release 19.4.1 · docs.gitlab.com
  13. Claude Code: requested scope is invalid · github.com
  14. MCP: bound tool response sizes and add a concise/detailed response option · gitlab.com
  15. Claude Code: MCP endpoint not found after sign-in · github.com

Updated Nov 1, 2026.