gitlab-mcp

A production-ready MCP server for GitLab. It lets AI assistants read and manage GitLab projects, merge requests, issues, pipelines, wikis, releases, and more through a broad, policy-controlled tool registry.

Highlights

• Comprehensive GitLab coverage — projects, merge requests (with code-context analysis), issues, pipelines, wikis, milestones, releases, labels, commits, branches, GraphQL, and file management
• Multiple transports — stdio for local CLI usage, Streamable HTTP for remote deployments, optional SSE
• Flexible authentication — personal access tokens, OAuth 2.0 PKCE, external token scripts, token files, cookie-based auth, and per-request remote authorization
• Policy engine — readonly/modify/full modes, tool allowlist/denylist, feature toggles, and project-scoped restrictions
• Enterprise networking — HTTP/HTTPS proxy, custom CA certificates, Cloudflare bypass, multi-instance API rotation
• Output control — JSON, compact JSON, or YAML formatting with configurable response size limits

Usage

Supported clients

Claude Desktop, Claude Code, VS Code, GitHub Copilot Chat (VS Code), Cursor, JetBrains AI Assistant, GitLab Duo, and any MCP client that supports stdio or streamable HTTP.

Current client format references:

• MCP transports and protocol
• Claude Code MCP
• VS Code MCP servers
• Cursor MCP
• JetBrains AI Assistant MCP

Authentication methods

The server supports three auth patterns:

1. Personal Access Token (PAT)
2. OAuth 2.0 PKCE (recommended for local interactive use)
3. Remote per-request auth (REMOTE_AUTHORIZATION=true, HTTP mode)

OAuth2 setup (stdio, recommended for local interactive use)

1. Create a GitLab OAuth application in Settings -> Applications.
2. Set redirect URI to http://127.0.0.1:8765/callback (or your custom callback).
3. Set scope to api.
4. Copy the Application ID as GITLAB_OAUTH_CLIENT_ID.

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "gitlab-mcp@latest"],
      "env": {
        "GITLAB_USE_OAUTH": "true",
        "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8765/callback",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_ALLOWED_PROJECT_IDS": "",
        "GITLAB_PERMISSION_MODE": "full",
        "USE_GITLAB_WIKI": "true",
        "USE_MILESTONE": "true",
        "USE_PIPELINE": "true"
      }
    }
  }
}

If your OAuth app is confidential, also set GITLAB_OAUTH_CLIENT_SECRET.

Personal Access Token setup (stdio)

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "gitlab-mcp@latest"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpa…[redacted]",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_ALLOWED_PROJECT_IDS": "",
        "GITLAB_PERMISSION_MODE": "full",
        "USE_GITLAB_WIKI": "true",
        "USE_MILESTONE": "true",
        "USE_PIPELINE": "true"
      }
    }
  }
}

VS Code .vscode/mcp.json examples

PAT with secure prompt input:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitlab_token",
      "description": "GitLab Personal Access Token",
      "password": true
    }
  ],
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${input:gitlab_token}",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_PERMISSION_MODE": "full"
      }
    }
  }
}

OAuth (confidential app) with secure prompt input:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitlab_oauth_secret",
      "description": "GitLab OAuth Client Secret",
      "password": true
    }
  ],
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
      "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:8765/callback",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

GitHub Copilot Chat in VS Code uses the same .vscode/mcp.json format.

Claude Desktop / Claude Code / Cursor

Claude Desktop reads claude_desktop_config.json. Claude Code supports project-level .mcp.json and claude mcp add-json. Cursor uses .cursor/mcp.json.

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpa…[redacted]",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

GitLab Duo (~/.gitlab/duo/mcp.json)

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpa…[redacted]",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  },
  "approvedTools": ["gitlab_get_project", "gitlab_list_merge_requests"]
}

JetBrains AI Assistant

JetBrains can import an existing MCP JSON config or register the server manually. Use stdio command node /absolute/path/to/gitlab-mcp/dist/index.js, or HTTP endpoint http://127.0.0.1:3333/mcp with required headers.

Remote authorization (multi-user HTTP)

Start server:

REMOTE_AUTHORIZATION=true \
HTTP_HOST=0.0.0.0 \
MCP_ALLOWED_HOSTS=127.0.0.1 \
HTTP_PORT=3333 \
node dist/http.js

Client config:

{
  "mcpServers": {
    "gitlab": {
      "url": "http://127.0.0.1:3333/mcp",
      "headers": {
        "Authorization": "Bearer glpa…[redacted]"
      }
    }
  }
}

Dynamic per-request API URL:

REMOTE_AUTHORIZATION=true \
ENABLE_DYNAMIC_API_URL=true \
HTTP_HOST=0.0.0.0 \
MCP_ALLOWED_HOSTS=127.0.0.1 \
HTTP_PORT=3333 \
node dist/http.js

Add header in client requests:

{
  "headers": {
    "Authorization": "Bearer glpa…[redacted]",
    "X-GitLab-API-URL": "https://gitlab.example.com/api/v4"
  }
}

Remote auth behavior matrix:

| Server Mode | Required Request Headers | Token Fallback Chain | | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------- | -------------------- | | REMOTE_AUTHORIZATION=false on local HTTP bind only | none | enabled | | REMOTE_AUTHORIZATION=true | Authorization: Bearer <token>, Private-Token: <token>, or Job-Token: <token> | disabled | | REMOTE_AUTHORIZATION=true + ENABLE_DYNAMIC_API_URL=true | Authorization, Private-Token, or Job-Token, and X-GitLab-API-URL: https://host/api/v4 | disabled |

When HTTP_HOST is not 127.0.0.1, localhost, or ::1, HTTP startup rejects server-side GITLAB_PERSONAL_ACCESS_TOKEN or GITLAB_JOB_TOKEN unless inbound requests are protected by MCP_HTTP_AUTH_TOKEN, REMOTE_AUTHORIZATION=true, or GITLAB_MCP_OAUTH=true.

Docker

For containerized deployments, PAT or remote auth is recommended. OAuth interactive callback flow is usually less convenient in containers. The Compose service listens on 0.0.0.0 inside the container but publishes only 127.0.0.1:3333 on the host by default. For the remote-authorization example, set REMOTE_AUTHORIZATION=true in .env, leave server-side GitLab credentials empty, and send each client's GitLab token as shown above.

docker compose up --build -d

or:

docker build -t gitlab-mcp .

docker run -d \
  --name gitlab-mcp \
  -p 127.0.0.1:3333:3333 \
  -e HTTP_HOST=0.0.0.0 \
  -e MCP_ALLOWED_HOSTS=127.0.0.1 \
  -e REMOTE_AUTHORIZATION=true \
  -e GITLAB_API_URL=https://gitlab.com/api/v4 \
  gitlab-mcp

Clients must send their GitLab credential in Authorization: Bearer <token>, Private-Token, or Job-Token. To keep a GitLab token in the container instead, set a separate 32+ character MCP_HTTP_AUTH_TOKEN and require clients to send that value as the bearer token; never expose a server-held GitLab token as the MCP bearer.

Compatibility notes

• GITLAB_PROJECT_ID is not a supported environment variable in this repository.
• To set an effective default project, use GITLAB_ALLOWED_PROJECT_IDS with one project ID, or pass project_id in tool arguments.
• CLI argument overrides such as --token or --api-url are not implemented (--env-file is supported).
• JSON config files do not support comments (//).

MCP Server Configuration

HTTP server

pnpm install
cp .env.example .env
pnpm build

# stdio (local MCP)
pnpm start

# streamable HTTP server (http://127.0.0.1:3333/mcp)
pnpm start:http

# optional: load a specific env file
pnpm start -- --env-file .env.local
pnpm start:http -- --env-file .env.local

Transport and entrypoint

| Transport | Entry Point | Endpoint | Best For | | ------------------- | -------------------- | ---------------------------- | ------------------------------------ | | stdio | node dist/index.js | stdin/stdout | Local single-user MCP clients | | Streamable HTTP | node dist/http.js | POST/GET/DELETE /mcp | Remote/shared deployments | | SSE (legacy) | node dist/http.js | GET /sse, POST /messages | Legacy SSE-only clients (SSE=true) | | Health | node dist/http.js | GET /healthz | Liveness/readiness checks |

SSE=true is not compatible with REMOTE_AUTHORIZATION=true.

Tool Categories

Tools are organized into these categories. All GitLab tools use the gitlab_ prefix, except health_check.

| Category | Examples | | ------------------- | ---------------------------------------------------------------------------- | | Projects | get_project, list_projects, create_repository, update_project | | Repository | get_repository_tree, get_file_contents, push_files, protected branches | | Merge Requests | list_merge_requests, get_merge_request_conflicts, merge_merge_request | | MR Code Context | get_merge_request_code_context (advanced code review) | | MR Discussions | list_merge_request_discussions, create_merge_request_thread | | MR Notes | list_merge_request_notes, create_merge_request_note | | Draft Notes | list_draft_notes, create_draft_note, bulk_publish_draft_notes | | Issues | list_issues, create_issue, update_issue, issue links | | Pipelines | list_pipelines, list_deployments, get_job_artifact_file