Better GitLab MCP Server

by zereight

447.5k downloads Not rated yet
GitHub Website

About

An improved GitLab MCP server with bug fixes and enhancements for accessing GitLab resources.

Explore

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name Better GitLab MCP Server
    Command (node, npx, python, etc.)

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

When usingREMOTE_AUTHORIZATION=true, the MCP server can support multiple users, each with their own GitLab token passed via HTTP headers. This is useful for:

- Shared MCP server instances where each user needs their own GitLab access
- IDE integrations that can inject user-specific tokens into MCP requests

# Start server with remote authorization docker run -d \ -e HOST=0.0.0.0 \ -e STREAMABLE_HTTP=true \ -e REMOTE_AUTHORIZATION=true \ -e GITLAB_API_URL="https://gitlab.com/api/v4" \ -e GITLAB_PERMISSION_MODE=readonly \ -e SESSION_TIMEOUT_SECONDS=3600 \ -p 3333:3002 \ zereight050/gitlab-mcp

Your IDE or MCP client must send one of these headers with each request:

Authorization: Bearer glpat-xxxxxxxxxxxxxxxxxxxx

Private-Token: glpat-xxxxxxxxxxxxxxxxxxxx

The token is stored per session (identified bymcp-session-idheader) and reused for subsequent requests in the same session.

{ "mcpServers": { "GitLab": { "url": "http(s)://<your_mcp_gitlab_server>/mcp", "headers": { "Authorization": "Bearer glpat-..." } } } }

- Remote authorizationonly works with Streamable HTTP transport
- Each session is isolated - tokens from one session cannot access another session's data Tokens are automatically cleaned up when sessions close
- Session timeout:Auth tokens expire afterSESSION_TIMEOUT_SECONDS(default 1 hour) of inactivity. After timeout, the client must send auth headers again. The transport session remains active.
- Each request resets the timeout timer for that session
- Rate limiting:/mcprequests are limited toMAX_REQUESTS_PER_MINUTEper client IP, and per MCP session when using OAuth or remote authorization (default 60). See](https://github.com/zereight/gitlab-mcp/blob/HEAD/docs/auth/oauth-callback-proxy.md)environment-variables.md.
- Capacity limit:Server accepts up toMAX_SESSIONSconcurrent sessions (default 1000)

When usingGITLAB_MCP_OAUTH=true, the server acts as an OAuth proxy to your GitLab instance. Claude.ai (and any MCP-spec-compliant client) handles the entire browser authentication flow automatically — no manual Personal Access Token management needed.

Apre-registered GitLab OAuth applicationis required. GitLab restricts dynamically registered (unverified) applications to themcpscope, which is insufficient for API calls (needapiorread_api).
- Go to your GitLab instance →Admin Area > Applications(instance-wide) orUser Settings > Applications(personal)
- Create a new application with:

- Confidential: unchecked
- Scopes:api,read_api,read_user(or whichever scopes you intend to request viaGITLAB_OAUTH_SCOPES)
- User adds your MCP server URL in Claude.ai
- Claude.ai discovers OAuth endpoints via/.well-known/oauth-authorization-server
- Claude.ai registers itself via Dynamic Client Registration (POST /register) — handled locally by the MCP server (each client gets a virtual client ID)
- Claude.ai redirects the user's browser to GitLab's login page using the pre-registered OAuth application
- User authenticates; GitLab redirects back tohttps://claude.ai/api/mcp/auth_callback
- Claude.ai sendsAuthorization: Bearer <token>on every MCP request
- Server validates the token with GitLab and stores it per session

docker run -d \ -e STREAMABLE_HTTP=true \ -e GITLAB_MCP_OAUTH=true \ -e GITLAB_OAUTH_APP_ID="your-gitlab-oauth-app-client-id" \ -e GITLAB_API_URL="https://gitlab.example.com/api/v4" \ -e MCP_SERVER_URL="https://your-mcp-server.example.com" \ -p 3002:3002 \ zereight050/gitlab-mcp

MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL=true \ STREAMABLE_HTTP=true \ GITLAB_MCP_OAUTH=true \ GITLAB_OAUTH_APP_ID=your-gitlab-oauth-app-client-id \ MCP_SERVER_URL=http://localhost:3002 \ GITLAB_API_URL=https://gitlab.com/api/v4 \ node build/index.js

{ "mcpServers": { "GitLab": { "url": "https://your-mcp-server.example.com/mcp" } } }

Noheadersfield is needed — Claude.ai obtains the token via OAuth automatically.

- MCP OAuthonly works with Streamable HTTP transport(SSE=trueis incompatible)
- Each user session stores its own OAuth token — sessions are fully isolated
- Session timeout, rate limiting, and capacity limits apply identically to theREMOTE_AUTHORIZATIONmode (SESSION_TIMEOUT_SECONDS,MAX_REQUESTS_PER_MINUTE,MAX_SESSIONS)
- DCR rate limiting:POST /registeris limited toOAUTH_REGISTER_RATE_LIMIT_PER_HOURper client IP (default 20/hour). Separate from/mcplimits and GitLab API quotas. Seeenvironment-variables.md.
- Header auth fallback:whenPrivate-TokenorJOB-TOKENrequest headers are present, OAuth validation is skipped and the raw token is used directly for that session. This allows PATs and CI job tokens to be used alongside the OAuth flow on the same server instance.Authorization: Beareris always treated as an OAuth token — usePrivate-Tokenfor PAT-based header auth.

Pre-built skill files are available inskills/gitlab-mcp/for AI agents that support skill/instruction loading (Claude Code, GitHub Copilot, Cursor, etc.).

- SKILL.md— Core guide (~800 tokens) with toolset overview, key workflows, and parameter hints
- reference/— Detailed workflow docs for code review, merge requests, issues, pipelines, and vulnerability triage

npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "better gitlab mcp server": {
            "server": {
                "command": "npx",
                "args": [
                    "-y",
                    "@zereight/mcp-gitlab"
                ],
                "env": {
                    "GITLAB_PERSONAL_ACCESS_TOKEN": "",
                    "GITLAB_JOB_TOKEN": "",
                    "GITLAB_AUTH_COOKIE_PATH": "",
                    "GITLAB_API_URL": "",
                    "GITLAB_ALLOWED_PROJECT_IDS": "",
                    "GITLAB_READ_ONLY_MODE": "",
                    "USE_GITLAB_WIKI": "",
                    "GITLAB_TOOLSETS": "",
                    "GITLAB_TOOLS": "",
                    "GITLAB_DENIED_TOOLS_REGEX": "",
                    "GITLAB_TOOL_POLICY_APPROVE": "",
                    "GITLAB_TOOL_POLICY_HIDDEN": "",
                    "NODE_TLS_REJECT_UNAUTHORIZED": "",
                    "GITLAB_CA_CERT_PATH": "",
                    "GITLAB_MASKING_ENABLED": "",
                    "GITLAB_MASKING_CONFIG": "",
                    "GITLAB_MASKING_POLICY_FILE": "",
                    "GITLAB_MASKING_WORKSPACE_DIR": ""
                }
            }
        }
    }
}

McpServers

{
    "server": {
        "command": "npx",
        "args": [
            "-y",
            "@zereight/mcp-gitlab"
        ],
        "env": {
            "GITLAB_PERSONAL_ACCESS_TOKEN": "",
            "GITLAB_JOB_TOKEN": "",
            "GITLAB_AUTH_COOKIE_PATH": "",
            "GITLAB_API_URL": "",
            "GITLAB_ALLOWED_PROJECT_IDS": "",
            "GITLAB_READ_ONLY_MODE": "",
            "USE_GITLAB_WIKI": "",
            "GITLAB_TOOLSETS": "",
            "GITLAB_TOOLS": "",
            "GITLAB_DENIED_TOOLS_REGEX": "",
            "GITLAB_TOOL_POLICY_APPROVE": "",
            "GITLAB_TOOL_POLICY_HIDDEN": "",
            "NODE_TLS_REJECT_UNAUTHORIZED": "",
            "GITLAB_CA_CERT_PATH": "",
            "GITLAB_MASKING_ENABLED": "",
            "GITLAB_MASKING_CONFIG": "",
            "GITLAB_MASKING_POLICY_FILE": "",
            "GITLAB_MASKING_WORKSPACE_DIR": ""
        }
    }
}

Transport

"stdio"

Package

"@zereight/mcp-gitlab"

Registry

"npm"

An improved GitLab MCP server with bug fixes and enhancements for accessing GitLab resources.

📖Documentation →Setup guides, environment variables, and the full tool reference live on the hosted docs site.

A comprehensive GitLab MCP server for AI clients. Manage projects, merge requests, issues, pipelines, wiki, releases, tags, milestones, and more through stdio, SSE, and Streamable HTTP.

Supports PAT, OAuth, read-only mode, dynamic API URLs, and remote authorization for VS Code, Claude, Cursor, Copilot, and other MCP clients.

- Broad GitLab coverage — projects, repository browsing, merge requests, issues, pipelines, wiki, releases, tags, labels, milestones, and more
- Flexible auth — Personal Access Token, local OAuth2 browser flow, MCP OAuth proxy, and per-request remote authorization
- Multiple transports — stdio for local clients, SSE for legacy clients, and Streamable HTTP for modern remote deployments
- Client-friendly setup — examples for Claude Code, Codex, Antigravity, OpenCode, Copilot, Cline, Roo Code, Cursor, Kilo Code, and Amp Code
- Self-hosted ready — works with custom GitLab instances, proxy settings, and dynamic API URL routing

Quick start: choose either Personal Access Token or OAuth2 setup below, install@zereight/mcp-gitlab, and usezereight-mcp-gitlabin your MCP client configuration.

- Claude Code Setup Guide
- VS Code Setup Guide
- GitHub Copilot Setup Guide
- Codex Setup Guide
- Cursor Setup Guide
- JSON-Based MCP Clients Setup Guide- for Factory AI Droid, OpenClaw, and OpenCode style clients
- OAuth2 Authentication Setup Guide
- Environment Variables Reference
- Stateless Mode — Multi-Pod HPA
- Custom Agents and Multiple PAT Setup

The server supports four authentication methods:
- Personal Access Token(GITLAB_PERSONAL_ACCESS_TOKEN) — simplest setup
- OAuth2 — Local Browser(GITLAB_USE_OAUTH) — recommended for better security
- OAuth2 — MCP Proxy(GITLAB_MCP_OAUTH) — for remote MCP clients such as Claude.ai
- Remote Authorization(REMOTE_AUTHORIZATION) — multi-user deployments where each caller provides their own token

- Claude Code: seeClaude Code Setup Guide
- VS Code: seeVS Code Setup Guide
- GitHub Copilot: seeGitHub Copilot Setup Guide
- Codex: seeCodex Setup Guide
- Cursor: seeCursor Setup Guide
- Factory AI Droid / OpenClaw / OpenCode style clients: seeJSON-Based MCP Clients Setup Guide
- OAuth browser flow details: seeOAuth2 Authentication Setup Guide

For the simplest local setup, start with a Personal Access Token. For browser-based local auth, use OAuth2. For remote or multi-user deployments, continue to the MCP OAuth and Remote Authorization sections later in this README.

brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp brew install zereight/gitlab-mcp/zereight-mcp-gitlab

The examples usezereight-mcp-gitlab, a less collision-prone alias for the legacymcp-gitlabbinary. If your MCP client cannot find it, use the absolute path fromwhich zereight-mcp-gitlab.

No global install? Pinnpxto the previous stable release (the version these docs recommend), for examplenpx -y @zereight/[email protected]. If you always want the newest release, usenpx -y @zereight/mcp-gitlab@latestinstead. The server prints a notice to stderr on startup when a newer version is available (disable withGITLAB_DISABLE_VERSION_CHECK=true).

Using CLI Arguments (for clients with env var issues)

Some MCP clients (like GitHub Copilot CLI) have issues with environment variables. Use CLI arguments instead:

{ "mcpServers": { "gitlab": { "command": "zereight-mcp-gitlab", "args": ["--token=YOUR_GITLAB_TOKEN", "--api-url=https://gitlab.com/api/v4"], "tools": ["*"] } } }

- --token- GitLab Personal Access Token (replacesGITLAB_PERSONAL_ACCESS_TOKEN)
- --api-url- GitLab API URL (replacesGITLAB_API_URL)
- --read-only=true- Enable read-only mode (replacesGITLAB_READ_ONLY_MODE, deprecated — prefer--permission-mode=readonly)
- --permission-mode- Permission level:readonly,modify(no delete tools), orfull(replacesGITLAB_PERMISSION_MODE, defaultfull)
- --use-wiki=true- Enable wiki API (replacesUSE_GITLAB_WIKI, legacy — preferGITLAB_TOOLSETS=wiki)
- --use-milestone=true- Enable milestone API (replacesUSE_MILESTONE, legacy — preferGITLAB_TOOLSETS=milestones)
- --use-pipeline=true- Enable pipeline API (replacesUSE_PIPELINE, legacy — preferGITLAB_TOOLSETS=pipelines)
- --disable-version-check=true- Disable the startup new-version notice (replacesGITLAB_DISABLE_VERSION_CHECK)

CLI arguments take precedence over environment variables.

Fine-grained tool filtering:useGITLAB_PERMISSION_MODE=modifyto allow create/update while blocking every delete tool (including delete mutations throughexecute_graphql), orGITLAB_PERMISSION_MODE=readonlyfor read-only access. You can also enable toolset groups withGITLAB_TOOLSETS=<group,…>, allow-list individual tools withGITLAB_TOOLS=<tool,…>(e.g. read-only groups plus a few specific write tools), and deny-list by pattern withGITLAB_DENIED_TOOLS_REGEX. The legacyUSE_GITLAB_WIKI/USE_MILESTONE/USE_PIPELINEflags are kept for backward compatibility only. SeeTools Referenceand[Environment Variables.

docker run -i --rm \ -e HOST=0.0.0.0 \ -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \ -e GITLAB_API_URL="https://gitlab.com/api/v4" \ -e GITLAB_PERMISSION_MODE=readonly \ -e GITLAB_TOOLSETS=wiki,milestones,pipelines \ -e SSE=true \ -e SSE_AUTH_TOKEN=your_mcp_sse_token \ -p 3333:3002 \ zereight050/gitlab-mcp

{ "mcpServers": { "gitlab": { "type": "sse", "url": "http://localhost:3333/sse", "headers": { "Authorization": "Bearer your_mcp_sse_token" } } } }

docker run -i --rm \ -e HOST=0.0.0.0 \ -e REMOTE_AUTHORIZATION=true \ -e GITLAB_API_URL="https://gitlab.com/api/v4" \ -e GITLAB_PERMISSION_MODE=readonly \ -e GITLAB_TOOLSETS=wiki,milestones,pipelines \ -e STREAMABLE_HTTP=true \ -p 3333:3002 \ zereight050/gitlab-mcp

{ "mcpServers": { "gitlab": { "type": "streamable-http", "url": "http://localhost:3333/mcp", "headers": { "Authorization": "Bearer glpat-..." } } } }
Using MCP OAuth Proxy (GITLAB_MCP_OAUTH)

For server/remote deployments only.This mode requires the MCP server to be deployed with a publicly accessible HTTPS URL. For local/desktop use, seeGITLAB_USE_OAUTHabove.

…

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

More like this

Similar MCP servers you might find useful

Browse category

Sequential Thinking

Sequential Thinking is an MCP server that provides a tool for dynamic and reflective problem-solving through a structured, step-by-step thinking process. It is…

— 88.2k 508.3k dl
Other

Sentry

Sentry MCP Server connects compatible AI clients with Sentry error monitoring, allowing models and agents to inspect issues and event data through Model…

— 88.1k 4.3k dl
Developer Tools

Github

GitHub MCP Server connects compatible AI clients with GitHub repositories, issues, and pull requests, allowing models and agents to read and act on project…

— 88.1k 9.9k dl
Developer Tools

Filesystem

Filesystem is a Node.js server that implements the Model Context Protocol (MCP) for filesystem operations. It enables AI assistants to read, write, and manage…

— 88.1k 6.7k dl
Other