Skip to content
MCP server

GitLab MCP Server

GitLab MCP server for projects, merge requests, issues, pipelines, wikis and releases

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

About GitLab MCP Server

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

This server starts with a lean set of 40 tools and can grow to 288 on demand. That choice is about context cost: the README measures about 12k schema tokens for the default and about 73k with everything loaded, so a discover_tools call activates extra toolsets for the session instead.

Two tools for merge request review stand out: one lists changed files and another returns batched file diffs, and a pipeline tool returns paginated job logs. An execute_graphql tool covers anything else GitLab's GraphQL API exposes. Auth options include personal access tokens, job tokens, OAuth flows and per-request remote authorisation.

Admins can narrow it with a readonly, modify or full permission mode, an allowed project id list, a denied-tool regex and named toolsets. It works with GitLab.com and self-managed instances, over stdio, legacy SSE or Streamable HTTP, and is distributed through npm and Homebrew.

Install

Run in a terminal

claude mcp add gitlab-mcp --env GITLAB_PERSONAL_ACCESS_TOKEN='<GITLAB_PERSONAL_ACCESS_TOKEN>' --env GITLAB_JOB_TOKEN='<GITLAB_JOB_TOKEN>' -- npx -y @zereight/mcp-gitlab

Add to claude_desktop_config.json

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<GITLAB_PERSONAL_ACCESS_TOKEN>",
        "GITLAB_JOB_TOKEN": "<GITLAB_JOB_TOKEN>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<GITLAB_PERSONAL_ACCESS_TOKEN>",
        "GITLAB_JOB_TOKEN": "<GITLAB_JOB_TOKEN>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "gitlab-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<GITLAB_PERSONAL_ACCESS_TOKEN>",
        "GITLAB_JOB_TOKEN": "<GITLAB_JOB_TOKEN>"
      }
    }
  }
}

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

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<GITLAB_PERSONAL_ACCESS_TOKEN>",
        "GITLAB_JOB_TOKEN": "<GITLAB_JOB_TOKEN>"
      }
    }
  }
}

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

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<GITLAB_PERSONAL_ACCESS_TOKEN>",
        "GITLAB_JOB_TOKEN": "<GITLAB_JOB_TOKEN>"
      }
    }
  }
}

Configuration

  • GITLAB_PERSONAL_ACCESS_TOKENGitLab personal access token for local stdio use. A non-empty value overrides GITLAB_PERSONAL_ACCESS_TOKEN_FILE. One of this token, GITLAB_PERSONAL_ACCESS_TOKEN_FILE, GITLAB_JOB_TOKEN, GITLAB_AUTH_COOKIE_PATH, or GITLAB_USE_OAUTH=true must be set. Create a token with the GitLab scopes the tools need, such as api or read_api.
  • GITLAB_PERSONAL_ACCESS_TOKEN_FILEPath to a file that contains the personal access token. Read once at startup and trimmed. Ignored when GITLAB_PERSONAL_ACCESS_TOKEN or --token is non-empty. A missing, unreadable, or empty file stops startup. Does not replace job token, OAuth, cookie, or remote authorization.
  • GITLAB_JOB_TOKENOptional GitLab CI job token to use instead of a personal access token when running inside GitLab CI.
  • GITLAB_AUTH_COOKIE_PATHOptional path to a GitLab authentication cookie file for cookie-based authentication.
  • GITLAB_USE_OAUTHSet to true to start with GitLab OAuth instead of a personal access token, job token, or cookie file.
  • GITLAB_OAUTH_CLIENT_IDGitLab OAuth application ID. When GITLAB_USE_OAUTH=true, set this or GITLAB_OAUTH_TOKEN_SCRIPT.
  • GITLAB_OAUTH_TOKEN_SCRIPTCommand that prints an OAuth access token. When GITLAB_USE_OAUTH=true, set this or GITLAB_OAUTH_CLIENT_ID.
  • GITLAB_API_URLGitLab API base URL. Use https://gitlab.com/api/v4 for GitLab.com or your self-managed GitLab API URL.
  • GITLAB_ALLOWED_PROJECT_IDSOptional comma-separated list of GitLab project IDs that this server is allowed to access.
  • GITLAB_PERMISSION_MODETool exposure. Allowed values are readonly, modify, and full. Unset uses full. readonly keeps read-only tools. modify blocks delete and teardown tools.
  • GITLAB_TOOLSETSOptional comma-separated toolset ids (projects, issues, merge_requests, …). Unset keeps the lean core default plus discover_tools. Do not set all unless you accept loading ~all schemas (~73k tokens).
  • GITLAB_TOOLSOptional comma-separated list of individual tool names to add on top of enabled toolsets.
  • GITLAB_DENIED_TOOLS_REGEXOptional regular expression used to hide matching tools from the server.
  • GITLAB_TOOL_POLICY_APPROVEOptional comma-separated list of tool names that require explicit approval before execution.
  • GITLAB_TOOL_POLICY_HIDDENOptional comma-separated list of tool names to hide from tools/list.
  • NODE_TLS_REJECT_UNAUTHORIZEDSet to 0 only when you intentionally need to connect to a GitLab instance with invalid or self-signed TLS certificates.
  • GITLAB_CA_CERT_PATHOptional path to a custom CA certificate file for self-managed GitLab instances.
  • GITLAB_MASKING_ENABLEDSet to true to mask text tool results and returned errors using built-in or configured rules.
  • GITLAB_MASKING_CONFIGOptional path to a response-masking JSON configuration file.
  • GITLAB_MASKING_POLICY_FILEOptional protected server-owned JSON file containing managed masking policies.
  • GITLAB_MASKING_WORKSPACE_DIRDirectory used to resolve response-masking configuration paths.
  • GITLAB_PERSONAL_ACCESS_TOKENGitLab personal access token for local stdio use. A non-empty value overrides GITLAB_PERSONAL_ACCESS_TOKEN_FILE. One of this token, GITLAB_PERSONAL_ACCESS_TOKEN_FILE, GITLAB_JOB_TOKEN, GITLAB_AUTH_COOKIE_PATH, or GITLAB_USE_OAUTH=true must be set. Create a token with the GitLab scopes the tools need, such as api or read_api.
  • GITLAB_PERSONAL_ACCESS_TOKEN_FILEPath to a file that contains the personal access token. Read once at startup and trimmed. Ignored when GITLAB_PERSONAL_ACCESS_TOKEN or --token is non-empty. A missing, unreadable, or empty file stops startup. Does not replace job token, OAuth, cookie, or remote authorization.
  • GITLAB_JOB_TOKENOptional GitLab CI job token to use instead of a personal access token when running inside GitLab CI.
  • GITLAB_AUTH_COOKIE_PATHOptional path to a GitLab authentication cookie file for cookie-based authentication.
  • GITLAB_USE_OAUTHSet to true to start with GitLab OAuth instead of a personal access token, job token, or cookie file.
  • GITLAB_OAUTH_CLIENT_IDGitLab OAuth application ID. When GITLAB_USE_OAUTH=true, set this or GITLAB_OAUTH_TOKEN_SCRIPT.
  • GITLAB_OAUTH_TOKEN_SCRIPTCommand that prints an OAuth access token. When GITLAB_USE_OAUTH=true, set this or GITLAB_OAUTH_CLIENT_ID.
  • GITLAB_API_URLGitLab API base URL. Use https://gitlab.com/api/v4 for GitLab.com or your self-managed GitLab API URL.
  • GITLAB_ALLOWED_PROJECT_IDSOptional comma-separated list of GitLab project IDs that this server is allowed to access.
  • GITLAB_PERMISSION_MODETool exposure. Allowed values are readonly, modify, and full. Unset uses full. readonly keeps read-only tools. modify blocks delete and teardown tools.
  • GITLAB_TOOLSETSOptional comma-separated toolset ids (projects, issues, merge_requests, …). Unset keeps the lean core default plus discover_tools. Do not set all unless you accept loading ~all schemas (~73k tokens).
  • GITLAB_TOOLSOptional comma-separated list of individual tool names to add on top of enabled toolsets.
  • GITLAB_DENIED_TOOLS_REGEXOptional regular expression used to hide matching tools from the server.
  • GITLAB_TOOL_POLICY_APPROVEOptional comma-separated list of tool names that require explicit approval before execution.
  • GITLAB_TOOL_POLICY_HIDDENOptional comma-separated list of tool names to hide from tools/list.
  • NODE_TLS_REJECT_UNAUTHORIZEDSet to 0 only when you intentionally need to connect to a GitLab instance with invalid or self-signed TLS certificates.
  • GITLAB_CA_CERT_PATHOptional path to a custom CA certificate file for self-managed GitLab instances.
  • GITLAB_MASKING_ENABLEDSet to true to mask text tool results and returned errors using built-in or configured rules.
  • GITLAB_MASKING_CONFIGOptional path to a response-masking JSON configuration file.
  • GITLAB_MASKING_POLICY_FILEOptional protected server-owned JSON file containing managed masking policies.
  • GITLAB_MASKING_WORKSPACE_DIRDirectory used to resolve response-masking configuration paths.

Tools this server provides (5)

Taken from the project documentation; the running server may differ.

discover_tools
Activates more toolsets for the session.
execute_graphql
Runs a GitLab GraphQL query.
list_merge_request_changed_files
Lists files changed in a merge request.
get_merge_request_file_diff
Returns batched file diffs for a merge request.
get_pipeline_job_output
Returns pipeline job output with pagination.

What it does

Lean default
40 tools by default, with more activated on request.
Permission modes
Readonly, modify or full tool exposure.
Project allow list
Restrict access to chosen project ids.
MR review tools
Changed-file lists and batched diffs.
Several auth methods
Tokens, OAuth, cookie file or remote authorisation.
Self-managed support
Point it at your own GitLab API URL.

Good for

  • Review a merge request from chat
  • Read failing pipeline job logs
  • Triage and update issues
  • Run an ad hoc GraphQL query
  • Give a team a read-only GitLab connector

Pricing

Open source

Free open-source package

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

GitLab MCP Server FAQ

How many tools exist?

288 in total, with 40 loaded by default.

Does it support self-hosted GitLab?

Yes, set GITLAB_API_URL.

Can I make it read-only?

Yes, with GITLAB_PERMISSION_MODE=readonly.

How do I run it?

npx -y @zereight/mcp-gitlab@latest, or install the binary with npm or Homebrew.

Is GitLab MCP Server free?

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

How do I add GitLab MCP Server to Claude Code?

Run this command in your terminal: claude mcp add gitlab-mcp --env GITLAB_PERSONAL_ACCESS_TOKEN='<GITLAB_PERSONAL_ACCESS_TOKEN>' --env GITLAB_JOB_TOKEN='<GITLAB_JOB_TOKEN>' -- npx -y @zereight/mcp-gitlab

What are the best alternatives to GitLab MCP Server?

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

Alternatives to GitLab MCP Server

  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