Skip to content
MCP server

GitLab

GitLab projects, merge requests, pipelines and CI/CD variables, with a read-only lock

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, self-hosted
Runs
Locally
Version
0.24.0
Listing updated
3 days ago

About GitLab

GitLab is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.

The README counts 91 tools, 7 resources and 6 prompts against the GitLab REST API, which is a wide surface for an assistant to work with. Areas include merge requests and code reviews, pipelines, CI/CD variables, approvals, issues and projects.

A read-only lock lets you offer a safer subset: with MCP_READ_ONLY=true the 57 write tools are not listed at all. MCP_TOOLSETS can also limit exposure to groups such as code, review, ci, issues, release or admin, which helps clients that cap how many tools they accept.

It works with GitLab.com and self-hosted CE or EE instances and needs neither GitLab Duo nor Premium. Authentication is a personal access token by default, or an OAuth 2.1 proxy mode over streamable-http. A Claude Code plugin stores the token in the credential store instead of a config file.

Install

Run in a terminal

claude mcp add mcp-gitlab --env GITLAB_TOKEN='<GITLAB_TOKEN>' --env GITLAB_URL='<GITLAB_URL>' --env GITLAB_OAUTH_CLIENT_SECRET='<GITLAB_OAUTH_CLIENT_SECRET>' --env GITLAB_OAUTH_JWT_KEY='<GITLAB_OAUTH_JWT_KEY>' --env GITLAB_HTTP_BEARER_TOKEN='<GITLAB_HTTP_BEARER_TOKEN>' -- uvx mcp-gitlab

Add to claude_desktop_config.json

{
  "mcpServers": {
    "mcp-gitlab": {
      "command": "uvx",
      "args": [
        "mcp-gitlab"
      ],
      "env": {
        "GITLAB_TOKEN": "<GITLAB_TOKEN>",
        "GITLAB_URL": "<GITLAB_URL>",
        "GITLAB_OAUTH_CLIENT_SECRET": "<GITLAB_OAUTH_CLIENT_SECRET>",
        "GITLAB_OAUTH_JWT_KEY": "<GITLAB_OAUTH_JWT_KEY>",
        "GITLAB_HTTP_BEARER_TOKEN": "<GITLAB_HTTP_BEARER_TOKEN>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "mcp-gitlab": {
      "command": "uvx",
      "args": [
        "mcp-gitlab"
      ],
      "env": {
        "GITLAB_TOKEN": "<GITLAB_TOKEN>",
        "GITLAB_URL": "<GITLAB_URL>",
        "GITLAB_OAUTH_CLIENT_SECRET": "<GITLAB_OAUTH_CLIENT_SECRET>",
        "GITLAB_OAUTH_JWT_KEY": "<GITLAB_OAUTH_JWT_KEY>",
        "GITLAB_HTTP_BEARER_TOKEN": "<GITLAB_HTTP_BEARER_TOKEN>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "mcp-gitlab": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-gitlab"
      ],
      "env": {
        "GITLAB_TOKEN": "<GITLAB_TOKEN>",
        "GITLAB_URL": "<GITLAB_URL>",
        "GITLAB_OAUTH_CLIENT_SECRET": "<GITLAB_OAUTH_CLIENT_SECRET>",
        "GITLAB_OAUTH_JWT_KEY": "<GITLAB_OAUTH_JWT_KEY>",
        "GITLAB_HTTP_BEARER_TOKEN": "<GITLAB_HTTP_BEARER_TOKEN>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-gitlab": {
      "command": "uvx",
      "args": [
        "mcp-gitlab"
      ],
      "env": {
        "GITLAB_TOKEN": "<GITLAB_TOKEN>",
        "GITLAB_URL": "<GITLAB_URL>",
        "GITLAB_OAUTH_CLIENT_SECRET": "<GITLAB_OAUTH_CLIENT_SECRET>",
        "GITLAB_OAUTH_JWT_KEY": "<GITLAB_OAUTH_JWT_KEY>",
        "GITLAB_HTTP_BEARER_TOKEN": "<GITLAB_HTTP_BEARER_TOKEN>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "mcp-gitlab": {
      "command": "uvx",
      "args": [
        "mcp-gitlab"
      ],
      "env": {
        "GITLAB_TOKEN": "<GITLAB_TOKEN>",
        "GITLAB_URL": "<GITLAB_URL>",
        "GITLAB_OAUTH_CLIENT_SECRET": "<GITLAB_OAUTH_CLIENT_SECRET>",
        "GITLAB_OAUTH_JWT_KEY": "<GITLAB_OAUTH_JWT_KEY>",
        "GITLAB_HTTP_BEARER_TOKEN": "<GITLAB_HTTP_BEARER_TOKEN>"
      }
    }
  }
}

Configuration

  • GITLAB_TOKENGitLab personal access token (token mode). Optional after `mcp-gitlab auth login`; also accepts GITLAB_PAT, GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_API_TOKEN
  • GITLAB_URLGitLab instance URL (e.g. https://gitlab.com)Required
  • GITLAB_READ_ONLYAlias for MCP_READ_ONLY. Any value other than false/0/no/off/empty locks the server read-only; --read-only can only raise the lock
  • MCP_READ_ONLYLocks the server read-only: write tools and write-workflow prompts are not listed and nothing lifts the lock at runtime. Shared name across the mcp-* servers; set it in the deployer's env
  • MCP_TOOLSETSComma list of tool groups to expose (code, review, ci, issues, release, admin); unset or 'all' lists every tool. Shrinks tools/list for clients with a tool budget; MCP_READ_ONLY still applies after the selection
  • GITLAB_AUTHAuthentication mode: token (default) or oauth (OAuth 2.1 proxy; streamable-http only)
  • GITLAB_OAUTH_CLIENT_IDApplication ID of the GitLab OAuth app (oauth mode, or local sign-in on a self-managed instance)
  • GITLAB_OAUTH_CLIENT_SECRETSecret of the GitLab OAuth app (oauth mode)
  • GITLAB_OAUTH_BASE_URLPublic URL of this server, no trailing slash (oauth mode); redirect URI is <base>/auth/callback
  • GITLAB_OAUTH_SCOPESSpace-separated GitLab scopes required on every request (oauth mode; default api)
  • GITLAB_OAUTH_JWT_KEYFastMCP JWT signing key, >=32 random chars (oauth mode; defaults to one derived from the client secret)
  • GITLAB_HTTP_BEARER_TOKENBearer token (min 16 chars) required to bind an HTTP transport to a non-loopback host; clients send it as 'Authorization: Bearer <token>' (token mode; --auth oauth has its own sign-in)

What it does

Merge request work
Manages merge requests, approvals and code reviews through the API.
Pipelines and CI/CD
Covers pipelines and CI/CD variables.
Read-only mode
Hides the 57 write tools when MCP_READ_ONLY is set.
Toolset groups
Limits exposure to code, review, ci, issues, release or admin tools.
OAuth mode
Optional OAuth 2.1 proxy over streamable-http instead of a token.
Claude Code plugin
Installs from a marketplace and prompts for URL and token.

Good for

  • Summarize and review open merge requests
  • Check why a pipeline failed and inspect CI variables
  • Triage issues across a self-hosted GitLab
  • Run a locked-down read-only assistant on production projects

Pricing

Open source

MIT-licensed; installs with uvx.

Prices change. Check vish288.github.io before you buy.

GitLab FAQ

Does it work with self-hosted GitLab?

Yes, GitLab.com and self-hosted CE or EE instances; set GITLAB_URL.

Do I need GitLab Premium or Duo?

No, the README says neither is required.

How many tools does it have?

91 tools, 7 resources and 6 prompts, of which 57 are write tools.

How does it authenticate?

With a personal access token by default, or an OAuth app in oauth mode, which needs streamable-http.

Is GitLab free?

Yes. GitLab is open source, so you can use and self-host it for free.

How do I add GitLab to Claude Code?

Run this command in your terminal: claude mcp add mcp-gitlab --env GITLAB_TOKEN='<GITLAB_TOKEN>' --env GITLAB_URL='<GITLAB_URL>' --env GITLAB_OAUTH_CLIENT_SECRET='<GITLAB_OAUTH_CLIENT_SECRET>' --env GITLAB_OAUTH_JWT_KEY='<GITLAB_OAUTH_JWT_KEY>' --env GITLAB_HTTP_BEARER_TOKEN='<GITLAB_HTTP_BEARER_TOKEN>' -- uvx mcp-gitlab

What are the best alternatives to GitLab?

The closest alternatives to GitLab are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

Alternatives to GitLab

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  3. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  4. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools
  5. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  6. Ouroboros

    MCP server

    Spec-first layer that pins requirements and verifies results of AI coding agent work

    Runs locally
    • Open source
    • 6.4K GitHub stars
    • Developer tools