GitLab MCP server: connect Claude Code and Cursor to issues, MRs and pipelines

You write code with Claude Code, Cursor or Copilot, but everything around that code lives in GitLab: issues, merge requests, red pipelines, job logs. Each time you need context, you open a browser, copy a log and paste it into the chat. The GitLab MCP server connects AI assistants directly to GitLab through the Model Context Protocol (MCP). The AI reads issues, reviews MR diffs, inspects failed job logs, creates branches, commits and opens MRs, all with exactly your account's permissions.

Fact check: does GitLab really have an MCP server?

Yes. It is an official, documented feature on docs.gitlab.com. Milestones from its version history:

The MCP server is available on the Free, Premium and Ultimate tiers, on GitLab.com, Self-Managed and Dedicated.

Key benefits

• Less switching between windows: ask "why did MR 42's pipeline fail?" inside your IDE; the AI fetches the job log and points to the failing line.
• One standard for many clients: one endpoint works with Claude Code, Cursor, VS Code Copilot, Gemini CLI, Codex, Zed, Kiro and more.
• Uses your existing permissions: the AI only sees and does what your account is allowed to. GitLab checks permissions on every tool call.
• End-to-end automation: read an issue → create a branch → commit → open an MR → watch the pipeline, all in one conversation.

Which tools are available?

Tools are grouped into toolsets. The default toolsets cover most day-to-day work:

Step-by-step setup

1. Enable MCP access

An administrator must allow access to the MCP server. On GitLab.com, the setting is on the top-level group; on Self-Managed and Dedicated, it is at the instance level. The endpoint is https://<gitlab-host>/api/v4/mcp; on GitLab.com the host is gitlab.com.

2. Connect a client

Use the HTTP transport; it needs no extra dependencies. Claude Code:

claude mcp add -s user --transport http GitLab https://gitlab.com/api/v4/mcp
# inside Claude Code, run /mcp to sign in with OAuth in your browser

Cursor, Kiro and other clients that take a JSON config:

{
  "mcpServers": {
    "GitLab": {
      "type": "http",
      "url": "https://gitlab.com/api/v4/mcp"
    }
  }
}

Codex: run codex mcp add GitLab --url https://gitlab.com/api/v4/mcp, enable rmcp_client in ~/.codex/config.toml, then run codex mcp login GitLab. For clients that only support stdio (Claude Desktop, Zed), use the bridge npx -y mcp-remote <URL>; it requires Node.js 20 or later.

3. Authenticate

• The server accepts an OAuth token with the mcp scope (from dynamic client registration or a pre-created OAuth app), or a fine-grained personal access token with Execute permission on the MCP resource.
• Legacy personal access tokens, project tokens and group tokens are all rejected with 403 insufficient_scope.
• If an admin has turned off dynamic client registration (DCR), or your whole company shares one IP (DCR is limited to 10 registrations per hour per IP), pre-create one OAuth app with the mcp scope and "Confidential" unchecked.

4. Limit tools with headers (recommended)

"headers": {
  "X-Gitlab-Enabled-Mcp-Server-Toolsets": "merge_requests,ci",
  "X-Gitlab-Mcp-Server-Tool-Name-Prefix": "gl_"
}

Fewer tools means less context spent and fewer wrong tool picks by the AI. A tool name prefix avoids name clashes when you connect several GitLab instances at once. Use the value all to turn on every toolset.

Prompts you can use right away

• "Which merge requests am I asked to review?" (uses list_todos)
• "Which job failed in the latest pipeline of MR !42? Read the log and suggest a fix."
• "Read issue #1234, create a branch, fix the bug, commit and open an MR linked to the issue."
• "Summarise the unresolved threads in MR !57 and draft replies."
• "Merge MR !42 once its checks pass and remove the source branch."

Risks and caveats

• Prompt injection: issue text, comments or files can carry malicious instructions aimed at the AI. GitLab states that guarding against this is the user's responsibility, so use MCP only on GitLab objects you trust.
• Write access: some tools merge MRs, commit or cancel pipelines. Have your client ask for confirmation before every write tool; don't turn on auto-approve.
• Rate limits on GitLab.com: counted per user. The Free tier gets 60 calls per minute and 3,600 per hour; Premium and Ultimate get 600 per minute and 5,000 per hour. Going over the limit returns a 429 error.
• Seeing a tool in the list doesn't mean you can use it; permissions are still checked on each call.

How to apply it

• Dev: Add GitLab MCP to Claude Code or Cursor at user scope. Use it to read failed pipeline logs and draft MRs, but approve every write action yourself.
• Tech Lead: Standardise the configuration (enabled toolsets, prefix, a shared OAuth app) and add it to onboarding docs. Start with read-oriented toolsets, then open up write access gradually.
• PM: Ask the AI assistant "which MRs are stuck in review this week?" or "what's the status of milestone X's issues?" without asking a developer to pull the numbers.