GitLab MCP Server

New Feature: Dynamic GitLab API URL support with connection pooling! See Dynamic API URL Documentation for details.

@zereight/mcp-gitlab

GitLab MCP(Model Context Protocol) Server. Includes bug fixes and improvements over the original GitLab MCP server.

Usage

Using with Claude Code, Codex, Antigravity, OpenCode, Copilot, Cline, Roo Code, Cursor, Kilo Code, Amp Code

When using with the Claude App, you need to set up your API key and URLs directly.

Authentication Methods

The server supports two authentication methods:

1. Personal Access Token (traditional method)
2. OAuth2 (recommended for better security)

Using OAuth2 Authentication

OAuth2 provides a more secure authentication flow using browser-based authentication. When enabled, the server will:

1. Open your browser to GitLab's authorization page
2. Wait for you to approve the access
3. Store the token securely for future use
4. Automatically refresh the token when it expires

For detailed OAuth2 setup instructions, see OAuth Setup Guide.

Quick setup - first create a GitLab OAuth application:

1. Go to your GitLab instance: Admin area → Applications
2. Create a new application with:
   • Name: GitLab MCP Server (or any name you prefer)
   • Redirect URI: http://127.0.0.1:8888/callback
   • Scopes: Select api (provides complete read/write access to the API)
3. Copy the Application ID (this is your Client ID)

Then configure the MCP server with OAuth:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_USE_OAUTH": "true",
        "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
        "GITLAB_OAUTH_CLIENT_SECRET": "your_oauth_client_secret", // Required for Confidential apps only
        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8888/callback",
        "GITLAB_API_URL": "your_gitlab_api_url",
        "GITLAB_PROJECT_ID": "your_project_id", // Optional: default project
        "GITLAB_ALLOWED_PROJECT_IDS": "", // Optional: comma-separated list of allowed project IDs
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "false", // use wiki api?
        "USE_MILESTONE": "false", // use milestone api?
        "USE_PIPELINE": "false" // use pipeline api?
      }
    }
  }
}

Using Personal Access Token (traditional)

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "your_gitlab_api_url",
        "GITLAB_PROJECT_ID": "your_project_id", // Optional: default project
        "GITLAB_ALLOWED_PROJECT_IDS": "", // Optional: comma-separated list of allowed project IDs
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "false", // use wiki api?
        "USE_MILESTONE": "false", // use milestone api?
        "USE_PIPELINE": "false" // use pipeline api?
      }
    }
  }
}

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": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab",
        "--token=YOUR_GITLAB_TOKEN",
        "--api-url=https://gitlab.com/api/v4"
      ],
      "tools": ["*"]
    }
  }
}

Available CLI arguments:

• --token - GitLab Personal Access Token (replaces GITLAB_PERSONAL_ACCESS_TOKEN)
• --api-url - GitLab API URL (replaces GITLAB_API_URL)
• --read-only=true - Enable read-only mode (replaces GITLAB_READ_ONLY_MODE)
• --use-wiki=true - Enable wiki API (replaces USE_GITLAB_WIKI)
• --use-milestone=true - Enable milestone API (replaces USE_MILESTONE)
• --use-pipeline=true - Enable pipeline API (replaces USE_PIPELINE)

CLI arguments take precedence over environment variables.

vscode .vscode/mcp.json

Using OAuth2 (Non-Confidential - Recommended):

{
  "servers": {
    "GitLab-MCP": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_USE_OAUTH": "true",
        "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8888/callback",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "false",
        "USE_MILESTONE": "false",
        "USE_PIPELINE": "false"
      }
    }
  }
}

Using OAuth2 (Confidential):

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitlab-oauth-secret",
      "description": "GitLab OAuth Client Secret",
      "password": true
    }
  ],
  "servers": {
    "GitLab-MCP": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_USE_OAUTH": "true",
        "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
        "GITLAB_OAUTH_CLIENT_SECRET": "${input:gitlab-oauth-secret}",
        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8888/callback",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "false"
      }
    }
  }
}

Using Personal Access Token:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitlab-token",
      "description": "GitLab Personal Access Token",
      "password": true
    }
  ],
  "servers": {
    "GitLab-MCP": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${input:gitlab-token}",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "false",
        "USE_MILESTONE": "false",
        "USE_PIPELINE": "false"
      }
    }
  }
}

Strands Agents SDK (MCP Tools)

env_vars = {
        "GITLAB_PERSONAL_ACCESS_TOKEN": gitlab_access_token,
        "GITLAB_API_URL": gitlab_api_url,
        "USE_GITLAB_WIKI": use_gitlab_wiki
        # ......the rest of the optional parameters
}

stdio_gitlab_mcp_client = MCPClient(
        lambda: stdio_client(
            StdioServerParameters(
                command="npx",
                args=["-y", "@zereight/mcp-gitlab"],
                env=env_vars,
            )
        )
    )

Docker

Note: For Docker deployments, Personal Access Token is recommended. OAuth requires browser-based authentication and a local callback server, which does not work properly in containerized environments.

Using Personal Access Token (stdio) - Recommended:

{
  "mcpServers": {
    "gitlab": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITLAB_PERSONAL_ACCESS_TOKEN",
        "-e",
        "GITLAB_API_URL",
        "-e",
        "GITLAB_READ_ONLY_MODE",
        "-e",
        "USE_GITLAB_WIKI",
        "-e",
        "USE_MILESTONE",
        "-e",
        "USE_PIPELINE",
        "zereight050/gitlab-mcp"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "true",
        "USE_MILESTONE": "true",
        "USE_PIPELINE": "true"
      }
    }
  }
}

• sse

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_READ_ONLY_MODE=true \
  -e USE_GITLAB_WIKI=true \
  -e USE_MILESTONE=true \
  -e USE_PIPELINE=true \
  -e SSE=true \
  -p 3333:3002 \
  zereight050/gitlab-mcp

{
  "mcpServers": {
    "gitlab": {
      "type": "sse",
      "url": "http://localhost:3333/sse"
    }
  }
}

• streamable-http

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_READ_ONLY_MODE=true \
  -e USE_GITLAB_WIKI=true \
  -e USE_MILESTONE=true \
  -e USE_PIPELINE=true \
  -e STREAMABLE_HTTP=true \
  -p 3333:3002 \
  zereight050/gitlab-mcp

{
  "mcpServers": {
    "gitlab": {
      "type": "streamable-http",
      "url": "http://localhost:3333/mcp"
    }
  }
}

Environment Variables

Authentication Configuration

• GITLAB_PERSONAL_ACCESS_TOKEN: Your GitLab personal access token. Required in standard mode; not used when REMOTE_AUTHORIZATION=true or when using OAuth.
• GITLAB_USE_OAUTH: Set to true to enable OAuth2 authentication instead of personal access token.
• GITLAB_OAUTH_CLIENT_ID: The Client ID from your GitLab OAuth application. Required when using OAuth.
• GITLAB_OAUTH_CLIENT_SECRET: The Client Secret from your GitLab OAuth application. Required only for Confidential applications.
• GITLAB_OAUTH_REDIRECT_URI: The OAuth callback URL. Default: http://127.0.0.1:8888/callback
• GITLAB_OAUTH_TOKEN_PATH: Custom path to store the OAuth token. Default: ~/.gitlab-mcp-token.json
• REMOTE_AUTHORIZATION: When set to 'true', enables remote per-session authorization via HTTP headers. In this mode:
  • The server accepts GitLab PAT tokens from HTTP headers (Authorization: Bearer <token>, Private-Token: <token> or Job-Token: <token>) on a per-session basis
  • GITLAB_PERSONAL_ACCESS_TOKEN environment variable is not required and ignored
  • Only works with Streamable HTTP transport (STREAMABLE_HTTP=true) because session management was already handled by the transport layer
  • SSE transport is disabled - attempting to use SSE with remote authorization will cause the server to exit with an error
  • Each client session can use a different token, enabling multi-user support with secure session isolation
  • Tokens are stored per session and automatically cleaned up when sessions close or timeout
• SESSION_TIMEOUT_SECONDS: Session auth token timeout in seconds. Default: 3600 (1 hour). Valid range: 1-86400 seconds (recommended: 60+). After this period of inactivity, the auth token is removed but the transport session remains active. The client must provide auth headers again on the next request. Only applies when REMOTE_AUTHORIZATION=true.

General Configuration

• GITLAB_API_URL: Your GitLab API URL. (Default: https://gitlab.com/api/v4)

• GITLAB_PROJECT_ID: Default project ID. If set, Overwrite this value when making an API request.

• GITLAB_ALLOWED_PROJECT_IDS: Optional comma-separated list of allowed project IDs. When set with a single value, acts as a default project (like the old "lock" mode). When set with multiple values, restricts access to only those projects. Examples:

  • Single value 123: MCP server can only access project 123 and uses it as default
  • Multiple values 123,456,789: MCP server can access projects 123, 456, and 789 but requires explicit project ID in requests

• GITLAB_READ_ONLY_MODE: When set to 'true', restricts the server to only expose read-only operations. Useful for enhanced security or when write access is not needed. Also useful for using with Cursor and it's 40 tool limit.

• GITLAB_DENIED_TOOLS_REGEX: When set as a regular expression, it excludes the matching tools.

• USE_GITLAB_WIKI: Legacy flag. Wiki features are now enabled by default. When set to 'true', ensures wiki-related tools are included even if the wiki toolset is not explicitly listed in GITLAB_TOOLSETS.

• USE_MILESTONE: Legacy flag. Milestone features are now enabled by default. When set to 'true', ensures milestone-related tools are included even if the milestones toolset is not explicitly listed in GITLAB_TOOLSETS.

• USE_PIPELINE: Legacy flag. Pipeline features are now enabled by default. When set to 'true', ensures pipeline-related tools are included even if the pipelines toolset is not explicitly listed in GITLAB_TOOLSETS.

• GITLAB_TOOLSETS: Comma-separated list of toolset IDs to enable. When empty or unset, default toolsets are used. Set to "all" to enable every toolset. Available toolsets (default toolsets marked with *):

  • merge_requests* — MR operations, notes, discussions, draft notes, threads, versions, file diffs, conflicts (34 tools)
  • issues* — Issue CRUD, notes, links, discussions (14 tools)
  • repositories* — Search, create, file contents, push, fork, tree (7 tools)
  • branches* — Branch creation, commits, diffs (4 tools)
  • projects* — Project/namespace info, group projects, iterations (8 tools)
  • labels* — Label CRUD (5 tools)
  • pipelines* — Pipeline, job, deployment, environment, and artifact operations (19 tools)
  • milestones* — Milestone CRUD, issues, MRs, burndown (9 tools)
  • wiki* — Wiki page CRUD for projects and groups (10 tools)
  • releases* — Release CRUD, evidence, asset download (7 tools)
  • users* — User info, events, markdown upload, attachments (5 tools)
  • workitems — Work item CRUD via GraphQL, type conversion, statuses, custom fields, notes, timeline events (12 tools, opt-in)
  • webhooks — Webhook listing and event inspection (3 tools, opt-in)
  • search — Code search across projects, groups, or globally (3 tools, requires advanced search or exact code search enabled)

  Note: execute_graphql is not in any toolset and must be added individually via GITLAB_TOOLS if needed. Exposing arbitrary GraphQL would allow bypassing toolset boundaries (e.g. querying data that the user intentionally disabled via toolsets like wiki or pipelines), which is a security and permission-containment concern. Keeping execute_graphql out of all toolsets and requiring explicit opt-in via GITLAB_TOOLS=execute_graphql is intentional, to align with that principle rather than for backward compatibility. CLI arg: --toolsets

• GITLAB_TOOLS: Comma-separated list of individual tool names to add on top of the enabled toolsets (additive). Useful for cherry-picking specific tools without enabling an entire toolset. Example: GITLAB_TOOLS="list_pipelines,execute_graphql". CLI arg: --tools

  Combined logic: final tools = (tools from enabled toolsets) ∪ (GITLAB_TOOLS) ∪ (legacy flag overrides)

  Examples:

  # Default behavior (unchanged)
  GITLAB_PERSONAL_ACCESS_TOKEN=xxx npx @zereight/mcp-gitlab
  
  # Only issues and repositories
  GITLAB_TOOLSETS="issues,repositories" npx @zereight/mcp-gitlab
  
  # All toolsets
  GITLAB_TOOLSETS="all" npx @zereight/mcp-gitlab
  
  # Default toolsets + one extra pipeline tool
  GITLAB_TOOLS="list_pipelines" npx @zereight/mcp-gitlab
  
  # Specific toolsets + individual tools
  GITLAB_TOOLSETS="issues,merge_requests" GITLAB_TOOLS="list_pipelines,get_pipeline" npx @zereight/mcp-gitlab
  
  # Legacy flags still work (backward compatible)
  USE_PIPELINE=true npx @zereight/mcp-gitlab

• GITLAB_AUTH_COOKIE_PATH: Path to an authentication cookie file for GitLab instances that require cookie-based authentication. When provided, the cookie will be included in all GitLab API requests.

• SSE: When set to 'true', enables the Server-Sent Events transport.

• STREAMABLE_HTTP: When set to 'true', enables the Streamable HTTP transport. If both SSE and STREAMABLE_HTTP are set to 'true', the server will prioritize Streamable HTTP over SSE transport.

• GITLAB_COMMIT_FILES_PER_PAGE: The number of files per page that GitLab returns for commit diffs. This value should match the server-side GitLab setting. Adjust this if your GitLab instance uses a custom per-page value for commit diffs.

• GITLAB_REPO_FILE_ENCODING: Encoding for repository file create/update and related commit payloads sent to the GitLab API. Use text (default) or base64. Equivalent CLI: --repo-file-encoding=text|base64.

Performance & Security Configuration

• HOST: Server host address. Default: 127.0.0.1 (localhost only). Set to 0.0.0.0 to allow external connections (required for Docker with port forwarding).
• MAX_SESSIONS: Maximum number of concurrent sessions allowed. Default: 1000. Valid range: 1-10000. When limit is reached, new connections are rejected with HTTP 503.
• MAX_REQUESTS_PER_MINUTE: Rate limit per session in requests per minute. Default: 60. Valid range: 1-1000. Exceeded requests return HTTP 429.
• PORT: Server port. Default: 3002. Valid range: 1-65535.
• HTTP_PROXY: HTTP proxy server URL for outgoing requests. Example: http://proxy.example.com:8080. Supports HTTP/HTTPS and SOCKS proxies (URLs starting with socks:// or socks5://). CLI arg: --http-proxy
• HTTPS_PROXY: HTTPS proxy server URL for outgoing requests. Example: https://proxy.example.com:8080. Supports HTTP/HTTPS and SOCKS proxies. CLI arg: --https-proxy
• NO_PROXY: Comma-separated list of hosts that should bypass the proxy. Supports:
  • Exact hostname matches (e.g., localhost, gitlab.internal.com)
  • Domain suffix matches (e.g., .internal.com matches any subdomain)
  • IP addresses (e.g., 127.0.0.1, 192.168.1.1)
  • Port-specific matches (e.g., example.com:443)
  • Wildcard * to bypass proxy for all hosts
  • Example: NO_PROXY=localhost,127.0.0.1,.internal.com
  • CLI arg: --no-proxy

Monitoring Endpoints

When using Streamable HTTP transport, the following endpoints are available:

• /health: Health check endpoint returning server status, active sessions count, and uptime.
• /metrics: Detailed metrics including:
  • Active and total session counts
  • Authentication metrics (failures, expirations)
  • Rate limiting statistics
  • Resource usage (memory, uptime)
  • Configuration summary

Remote Authorization Setup (Multi-User Support)

When using REMOTE_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

Setup Example:

# 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_READ_ONLY_MODE=true \
  -e SESSION_TIMEOUT_SECONDS=3600 \
  -p 3333:3002 \
  zereight050/gitlab-mcp

Client Configuration:

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

Authorization: Bearer glpat-xxxxxxxxxxxxxxxxxxxx

or

Private-Token: glpat-xxxxxxxxxxxxxxxxxxxx

The token is stored per session (identified by mcp-session-id header) and reused for subsequent requests in the same session.

Remote Authorization Client Configuration Example with Cursor

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

Important Notes:

• Remote authorization only 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 after SESSION_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: Each session is limited to MAX_REQUESTS_PER_MINUTE requests per minute (default 60)
• Capacity limit: Server accepts up to MAX_SESSIONS concurrent sessions (default 1000)

MCP OAuth Setup (Claude.ai Native OAuth)

When using GITLAB_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.

Prerequisites:

A pre-registered GitLab OAuth application is required. GitLab restricts dynamically registered (unverified) applications to the mcp scope, which is insufficient for API calls (need api or read_api).

1. Go to your GitLab instance → Admin Area > Applications (instance-wide) or User Settings > Applications (personal)
2. Create a new application with:
   • Confidential: unchecked
   • Scopes: api, read_api, read_user
3. Save and copy the Application ID — this is your GITLAB_OAUTH_APP_ID

How it works:

1. User adds your MCP server URL in Claude.ai
2. Claude.ai discovers OAuth endpoints via /.well-known/oauth-authorization-server
3. Claude.ai registers itself via Dynamic Client Registration (POST /register) — handled locally by the MCP server (each client gets a virtual client ID)
4. Claude.ai redirects the user's browser to GitLab's login page using the pre-registered OAuth application
5. User authenticates; GitLab redirects back to https://claude.ai/api/mcp/auth_callback
6. Claude.ai sends Authorization: Bearer <token> on every MCP request
7. Server validates the token with GitLab and stores it per session

Server setup:

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

For local development (HTTP allowed):

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

Claude.ai configuration:

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

No headers field is needed — Claude.ai obtains the token via OAuth automatically.

Environment variables:

Important Notes:

• MCP OAuth only works with Streamable HTTP transport (SSE=true is incompatible)
• Each user session stores its own OAuth token — sessions are fully isolated
• Session timeout, rate limiting, and capacity limits apply identically to the REMOTE_AUTHORIZATION mode (SESSION_TIMEOUT_SECONDS, MAX_REQUESTS_PER_MINUTE, MAX_SESSIONS)

Tools 🛠️

Testing 🧪

The project includes comprehensive test coverage including remote authorization:

# Run all tests (API validation + remote auth)
npm test

# Run only remote authorization tests
npm run test:remote-auth

# Run all tests including readonly MCP tests
npm run test:all

# Run only API validation
npm run test:integration

All remote authorization tests use a mock GitLab server and do not require actual GitLab credentials.