GitLab MCP Server: Setup, Tokens, and Workflows for 2026

Table of Contents

1. What Is the GitLab MCP Server?
2. Official vs Community GitLab MCPs
3. Prerequisites
4. Step-by-Step Installation
5. GitLab Personal Access Token Scoping
6. What Claude Can Do With the GitLab MCP
7. Real Workflows
8. GitLab MCP vs GitHub MCP vs Local Git MCP
9. Common Errors and How to Fix Them
10. Security Checklist
11. Frequently Asked Questions

What Is the GitLab MCP Server?

The GitLab MCP server is a Model Context Protocol server that exposes the GitLab REST API as MCP tools. Once installed in your AI client, Claude (or any MCP-supporting client) can list and search projects, view and comment on merge requests, manage issues and labels, run and inspect CI/CD pipelines, browse repository files, create branches, post snippets, and manage environments. Essentially every action available in the GitLab UI is available to Claude through this MCP.

The MCP protocol itself was published by Anthropic in late 2024. By 2026 every major AI client supports it — Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Zed — which means installing the GitLab MCP once gives you GitLab capability in whichever client you happen to be using that day. For the broader landscape, read best Git MCP servers of 2026.

Official vs Community GitLab MCPs

Two flavors exist:

• The official GitLab MCP is maintained inside the GitLab MCP gateway project. It handles both gitlab.com and self-hosted GitLab, supports the full REST API surface, and ships in lockstep with GitLab releases.
• Community GitLab MCPs (several exist) wrap the same API with different ergonomics — usually a smaller install footprint or a more opinionated tool surface (project search only, for example, or MR review only). They are fine for niche workflows but less battle-tested than the official server.

We default to the official MCP in this guide. The community options are useful when you want a narrower attack surface or a more constrained tool set. Skiln tags every MCP with a trust score so you can make the choice with eyes open.

Prerequisites

Before installing, confirm you have:

• Node.js 20 or later (or Python 3.10+ if you choose a Python-based community variant). Most install commands use npx, which ships with Node.
• An MCP client. Claude Desktop, Claude Code, Cursor, Windsurf, Cline, or Zed. Read best MCP clients of 2026 if you have not picked one.
• A GitLab account with permission to create Personal Access Tokens. On free gitlab.com this is every account. On self-hosted instances, your admin may have token creation restricted.
• A target GitLab URL. Default is https://gitlab.com. Self-hosted users will need their instance URL ready.

Step-by-Step Installation

The official GitLab MCP server installs via npm. One-time test run:

npx -y @modelcontextprotocol/server-gitlab

If it boots without error, wire it into your client.

Configuring Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{   "mcpServers": {     "gitlab": {       "command": "npx",       "args": ["-y", "@modelcontextprotocol/server-gitlab"],       "env": {         "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-..."       }     }   } }

Restart Claude Desktop. A gitlab entry appears in the tools sidebar.

Configuring Claude Code

claude mcp add gitlab \   --env GITLAB_PERSONAL_ACCESS_TOKEN=glpat-... \   -- npx -y @modelcontextprotocol/server-gitlab

Reopen your Claude Code session and /mcp will list the new server.

Configuring for Self-Hosted GitLab

Add the GITLAB_URL environment variable in the same config block:

{   "mcpServers": {     "gitlab-onprem": {       "command": "npx",       "args": ["-y", "@modelcontextprotocol/server-gitlab"],       "env": {         "GITLAB_URL": "https://gitlab.your-company.com",         "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-..."       }     }   } }

You can run gitlab.com and self-hosted side by side with different server names — Claude will use whichever the prompt implies.

GitLab Personal Access Token Scoping

PATs are the single most important security knob. Three scopes matter:

• read_api — read-only access. Claude can list projects, view merge requests, read issues, fetch pipeline logs. Safe default for review and triage workflows.
• api — full read and write. Claude can comment on MRs, label and close issues, trigger pipelines, create branches, post snippets. Required for most "do work for me" patterns but should be paired with a dedicated AI bot account.
• read_repository — read the git tree itself. Useful when you want Claude to read source files without going through the MR API.

What to avoid:

• write_repository unless Claude is actually pushing commits. The local Git MCP is usually a safer choice for commits.
• sudo — never grant this to an AI-controlled token. Sudo lets the token act as any user on the instance and is a recipe for accidents.
• Long expiration dates. Set token expiry to 30 or 60 days and rotate. If a PAT leaks, the blast radius is bounded.

The pattern we recommend in production: a dedicated GitLab account named claude-bot, two PATs (one read-only for chat and triage, one full api for write workflows), tight project memberships, and a 60-day rotation cadence. Pair this with the Claude Code security best practices for the full picture.

What Claude Can Do With the GitLab MCP

The official server ships roughly 25 tools. The categories engineers reach for most:

• Projects: search, get details, list members, list branches, list contributors.
• Merge requests: list, get, list discussions, list notes, post a note, approve, merge.
• Issues: list, get, create, update, close, label, assign.
• Pipelines: list, get, list jobs, retry, cancel, trigger.
• Repository: list files, get file contents, list commits, create branch.
• Snippets: create, update, list.
• Environments: list, get, stop.

The "approve" and "merge" tools deserve their own line: be careful giving Claude permission to merge. Even with strong CI, an MR-merge action is irreversible relative to the comment thread. Most teams gate this behind a dedicated bot account that does not have permission to merge directly — it can only approve, and a human still presses the green button.

Real Workflows: MR Review, Pipelines, Issue Triage

Patterns that earn the MCP its keep:

1. The MR review pre-pass. Ask Claude to fetch the diff for an open merge request, read the description, scan for obvious issues (console.logs, missing tests, large file additions, exposed secrets), and post a structured review comment. Saves the human reviewer 5-10 minutes per MR and catches the easy stuff.

2. The pipeline triage loop. "Why did the latest pipeline on main fail?" Claude lists the failed jobs, fetches their logs, identifies the root-cause line, and proposes a fix. Combine with the local Git MCP and Claude can even open a fix branch and an MR.

3. The stale issue sweep. Once a quarter, ask Claude to list every open issue with no activity in 90+ days, group by label, draft a polite "we are closing this" message per group, and either close them in bulk or post the messages for human review.

4. The release-notes generator. Pass Claude a milestone or a tag range. It pulls the closed MRs, groups by label or scope, and produces a markdown changelog suitable for pasting into the release announcement.

5. The cross-MR consistency check. When several MRs touch the same area, ask Claude to diff them against each other and flag conflicts before merge order matters. Tedious by hand, trivial with the MCP.

GitLab MCP vs GitHub MCP vs Local Git MCP

Most teams install at least two of these together. The GitHub MCP is the most-installed git-related MCP in our directory; read the dedicated GitHub MCP server guide for the parallel walkthrough.

Common Errors and How to Fix Them

• "401 Unauthorized." PAT is wrong, expired, or missing the right scope. Regenerate with read_api (read-only) or api (full) and update the env var.
• "404 Project not found." The PAT is valid but does not have access to the requested project. On self-hosted, double-check the project's path namespace.
• "Network error talking to GitLab." Usually a wrong GITLAB_URL. Confirm with curl -H "PRIVATE-TOKEN: $PAT" $GITLAB_URL/api/v4/user.
• "npx command not found." Node.js is not installed or not on PATH. Install Node 20+ and reopen the terminal.
• "MCP not showing in Claude after install." Restart the client. If it still does not appear, check the client's MCP log file for a stack trace — almost every silent failure is a missing env var or a wrong path.

Security Checklist

Run through this list before exposing the GitLab MCP to a production GitLab account:

• [ ] Dedicated bot account (not a real user) owns the PAT.
• [ ] PAT is scoped to the minimum (read_api for triage, api only when write is required).
• [ ] Token expiration is set to 30-60 days.
• [ ] Project memberships are restricted to what the bot needs to touch.
• [ ] The bot does not have permission to merge MRs directly; humans still press the green button.
• [ ] Slack or email notifications fire on bot-owned MR comments so accidental noise is caught quickly.
• [ ] Tokens are stored in the MCP client config or a secret manager — never in a public dotfile.

Frequently Asked Questions

Is there an official GitLab MCP server?

Yes. GitLab maintains an MCP server that targets the public GitLab REST API. It works against gitlab.com out of the box and against self-hosted GitLab via a custom GITLAB_URL environment variable. Several community MCPs exist that wrap the same API with different ergonomics, but for production use the official server is the recommended starting point.

Can the GitLab MCP work with self-hosted GitLab?

Yes. Pass GITLAB_URL=https://gitlab.your-company.com in the MCP server env and the same Personal Access Token flow works. You will want a PAT with the api scope created on the self-hosted instance specifically (PATs are not portable across GitLab instances).

What scopes does my GitLab PAT need?

Minimum useful scope is read_api for read-only review and triage workflows. Add api (full read and write) if you want Claude to comment on merge requests, label issues, run pipelines, or create branches. Avoid write_repository unless Claude needs to push code, and never grant sudo to an AI-controlled token.

Does the GitLab MCP let Claude trigger pipelines?

Yes, with the api scope. Claude can list pipelines, view job logs, retry failed jobs, cancel running pipelines, and trigger new pipelines via the API. This is one of the biggest workflow wins because pipeline triage typically requires bouncing between the GitLab UI and the CLI; with the MCP it happens in chat.

Can I use this MCP with both GitLab.com and a self-hosted instance at the same time?

Yes. Configure two MCP server entries with different names (gitlab-cloud and gitlab-onprem, for example) and different GITLAB_URL plus token env vars. Most MCP clients let you have arbitrary numbers of MCP servers running in parallel, and Claude can use both in the same conversation.

Do MR (merge request) comments through the MCP look like they came from a bot?

They look like they came from the user whose PAT you used. There is no separate bot account unless you provision one. The recommended pattern is to create a dedicated GitLab account named claude-bot or ai-assistant, generate the PAT under that account, and give it write access only to the projects it needs. That way every AI-generated comment is clearly attributable.

Is the GitLab MCP free?

Yes. The MCP server is open source. You only pay for whatever GitLab plan you already use (Free, Premium, or Ultimate) and the underlying AI provider. There is no per-call MCP charge.

Where can I see other version-control MCP servers indexed on Skiln?

Browse /mcps and filter for git, gitlab, github, or version control. We track 400+ git-related MCP entries including the official GitLab MCP, the official GitHub MCP, Bitbucket MCP, Gitea MCP, the local git MCP, and specialized helpers like GitHub Project Manager.

Last updated: May 29, 2026 · Skiln tracks new MCP releases daily across 13 source registries including PulseMCP, Smithery, Glama, LobeHub, and mcp.directory.