GitLab MCP ServerFeatured

What is GitLab MCP Server?

GitLab MCP Server is a gitlab mcp integration that lets AI assistants search projects, read files, push commits, and open issues, branches, forks and merge requests through the GitLab API. This listing is the archived reference version; GitLab now ships an official, maintained MCP server.

The listed package, @modelcontextprotocol/server-gitlab, was one of the reference servers published by the Model Context Protocol project. It has moved to the servers-archived repository, which states that the servers there are no longer maintained and come with no security guarantees, and the npm package is marked as no longer supported. For new setups, use the official GitLab MCP server, a remote endpoint built into GitLab itself at /api/v4/mcp. Both options are covered below.

How to use GitLab MCP Server?

Official GitLab MCP server (recommended)

Prerequisites: access to the MCP server must be allowed for your top-level group on GitLab.com, or for the instance on GitLab Self-Managed and GitLab Dedicated. Authentication uses OAuth: on first connect the client registers itself (OAuth 2.0 Dynamic Client Registration), opens your browser, and you approve the request. The server also accepts a fine-grained personal access token with the MCP tool permission, but not legacy personal, project or group access tokens.

Replace <gitlab.example.com> with gitlab.com or your self-managed instance URL in the examples below.

Claude Code

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

Start claude, type /mcp, select the GitLab server and approve the authorization in your browser.

Claude Desktop

Requires Node.js 20 or later. Add this to claude_desktop_config.json and restart Claude Desktop:

{
  "mcpServers": {
    "GitLab": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<gitlab.example.com>/api/v4/mcp"]
    }
  }
}

Cursor

In Settings > Cursor Settings > Tools & MCP, add a new MCP server to mcp.json:

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

VS Code

Open the Command Palette, run MCP: Add Server, choose HTTP, enter https://<gitlab.example.com>/api/v4/mcp with the ID GitLab, then approve the OAuth request.

Codex

codex mcp add GitLab --url "https://<gitlab.example.com>/api/v4/mcp"
codex mcp login GitLab

GitLab's docs also ask you to enable rmcp_client under [features] in ~/.codex/config.toml.

Archived reference server (the config on this page)

Create a GitLab personal access token with the api scope (or read_api for read-only access), then run the package with npx:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

GITLAB_API_URL is optional and only needed for self-hosted instances. The README also documents a Docker image, mcp/gitlab.

Key features of GitLab MCP Server

• Official server is built into GitLab and available on Free, Premium and Ultimate for GitLab.com, Self-Managed and Dedicated; it became generally available in GitLab 19.5.
• No local install for HTTP clients: connect to https://<instance>/api/v4/mcp and sign in with OAuth.
• Tool groups (toolsets) such as core, merge_requests, work_items, repository and ci, selectable with the X-Gitlab-Enabled-Mcp-Server-Toolsets header.
• Optional tool-name prefix through the X-Gitlab-Mcp-Server-Tool-Name-Prefix header, useful when you connect several GitLab instances.
• Every tool call checks your own project and namespace permissions.
• The archived server creates missing branches automatically when creating or updating files, and supports single-file and multi-file commits without force pushing.

GitLab MCP Server tools

The archived reference server exposes the nine tools listed on this page:

• Repository and files: search_repositories, create_repository, fork_repository, create_branch, get_file_contents.
• Commits: create_or_update_file writes one file, and push_files pushes several files in a single commit.
• Collaboration: create_issue and create_merge_request (with draft support).

The official GitLab MCP server has a much larger, maintained set, including get_merge_request_diffs, save_merge_request_review, list_pipelines, get_job, list_work_items, semantic_search and vulnerability tools on Ultimate. See GitLab's MCP server tools documentation for the current list.

Use cases of GitLab MCP Server

• Code review: "Summarize the diff in merge request !42 and list risky changes."
• Issue triage: "Create an issue in my-group/api titled 'Login timeout' with the label bug."
• Small fixes from chat: "Create a branch fix-readme, update README.md and open a draft merge request."
• CI debugging (official server): "Why did the latest pipeline on main fail? Show the failing job log."
• Codebase questions: "Read src/config.ts on the develop branch and explain the defaults."

GitLab MCP Server vs alternatives

• Official GitLab MCP server vs this archived package: the official one is maintained by GitLab, uses OAuth instead of a long-lived token, covers pipelines, work items and reviews, and needs no local process for HTTP clients. The archived package only covers basic repository, issue and merge request operations.
• Community GitLab servers: projects such as GitLab MR MCP focus on merge requests and issues.
• GitHub instead of GitLab: use the GitHub MCP Server.

Troubleshooting GitLab MCP Server

• 403 Forbidden from the official server (404 Not Found in GitLab 19.4 and earlier): the MCP server is not allowed for your group or instance, or you used a legacy personal, project or group access token. Check the prerequisites and use OAuth or a fine-grained token.
• 429 Too Many Requests: you hit the MCP or API rate limit; requests fail until the limit resets.
• OAuth keeps failing with mcp-remote: delete the local auth cache with rm -rf ~/.mcp-auth/mcp-remote* and reconnect.
• Archived server returns auth errors: confirm GITLAB_PERSONAL_ACCESS_TOKEN has the api scope and that GITLAB_API_URL ends in /api/v4 for self-hosted GitLab.