Mcp Gitlab

GitLab MCP Server

[](https://www.npmjs.com/package/gitlab-mcp-cli) [](https://www.npmjs.com/package/gitlab-mcp-cli) [](https://github.com/DevquasarX9/mcp-gitlab/actions/workflows/ci.yml)

gitlab-mcp-server is a Model Context Protocol server for GitLab.com and self-managed GitLab. It runs over stdio by default and also supports opt-in Streamable HTTP for local clients that need an HTTP endpoint.

It gives AI agents and developer tools structured access to GitLab projects, repositories, issues, merge requests, pipelines, releases, governance data, and higher-level delivery summaries. The server is read-only by default and uses explicit gates for write and destructive actions.

• npm package: gitlab-mcp-cli
• Repository: DevquasarX9/mcp-gitlab
• Works with: Claude Code, Claude Desktop, Codex, Cursor, and other MCP clients

Why This Server

• Safe defaults: read-only mode is the default, with separate write and destructive-action gates.
• GitLab coverage: projects, groups, repositories, issues, merge requests, pipelines, releases, packages, approvals, and protected branches.
• AI-friendly tools: higher-level tools summarize project health, review risk, release notes, delivery status, and pipeline failures.
• Self-managed support: works with https://gitlab.com and private GitLab instances.
• Operational controls: allowlists, denylist, payload caps, timeout control, optional audit logging, and secret redaction.

When To Use This

Use this server when you want a local or self-managed GitLab MCP server with conservative defaults, explicit write gates, project/group allowlists, and workflow-oriented summaries. It is especially useful for agents that need to inspect repositories, review merge requests, triage CI, assess release readiness, or produce delivery digests without cloning repositories first.

The official GitLab MCP server is a good default when you want GitLab's beta hosted tool surface and Duo-backed features. glab mcp serve can be useful for CLI-centered experimentation. This package focuses on read-only-by-default local operation, guarded writes, broader GitLab API coverage, and higher-level DevOps workflow intelligence. See docs/parity.md for the current mapping.

Install

Requirements:

• Node.js >=20.11.0
• A GitLab token with the scopes needed for the resources you want to access

Install globally:

npm install -g gitlab-mcp-cli

Run without a global install:

npx -y gitlab-mcp-cli

The published package name is gitlab-mcp-cli. The installed executable is gitlab-mcp-server.

Quick Start

Run the server directly after setting the required environment variables:

GITLAB_BASE_URL=https://gitlab.com \
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx \
gitlab-mcp-server

From source:

npm ci
npm run build
GITLAB_BASE_URL=https://gitlab.com \
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx \
node dist/cli.js

For local development, copy .env.example to .env and keep credentials out of git.

Run a setup diagnostics pass before wiring the server into a client:

gitlab-mcp-server doctor

From source:

npm run build
node dist/cli.js doctor

The doctor report validates GitLab connectivity and summarizes:

• authenticated user and GitLab version
• read-only, write-enabled, or destructive-enabled posture
• token scope visibility when PAT introspection is available
• allowlists, denylist, and alias counts
• tool profile, HTTP bind posture, and payload limits
• likely blocked capabilities and recommended next checks

MCP Client Setup

Example client configs live in examples/clients/:

• Claude Code guide
• Shared client setup guide
• HTTP transport guide
• Raw config examples: Claude Desktop JSON, Codex TOML, Cursor JSON

Generic stdio config

{
  "mcpServers": {
    "gitlab": {
      "command": "gitlab-mcp-server",
      "env": {
        "GITLAB_BASE_URL": "https://gitlab.com",
        "GITLAB_TOKEN": "your-token-here",
        "ENABLE_WRITE_TOOLS": "false",
        "ENABLE_DESTRUCTIVE_TOOLS": "false"
      }
    }
  }
}

npx config

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "gitlab-mcp-cli"],
      "env": {
        "GITLAB_BASE_URL": "https://gitlab.com",
        "GITLAB_TOKEN": "your-token-here",
        "ENABLE_WRITE_TOOLS": "false",
        "ENABLE_DESTRUCTIVE_TOOLS": "false"
      }
    }
  }
}

Codex TOML config

[mcp_servers.gitlab]
command = "gitlab-mcp-server"

[mcp_servers.gitlab.env]
GITLAB_BASE_URL = "https://gitlab.com"
GITLAB_TOKEN = "your-token-here"
ENABLE_WRITE_TOOLS = "false"
ENABLE_DESTRUCTIVE_TOOLS = "false"

HTTP transport

Stdio remains the default transport. To run the local Streamable HTTP server, use the CLI subcommand:

GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx \
gitlab-mcp-server serve-http

You can also enable HTTP with environment configuration:

MCP_TRANSPORT=http \
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx \
gitlab-mcp-server

CLI mode takes precedence over MCP_TRANSPORT, so gitlab-mcp-server doctor still runs diagnostics even when MCP_TRANSPORT=http is present.

Default HTTP endpoint:

http://127.0.0.1:3333/mcp

HTTP safety defaults:

• Binds to 127.0.0.1.
• Allows localhost, 127.0.0.1, and [::1] host headers.
• Allows missing origins and localhost browser origins.
• Requires explicit MCP_HTTP_ALLOWED_ORIGINS entries for remote browser origins.
• Refuses non-local binds unless both MCP_HTTP_ALLOW_NON_LOCALHOST=true and MCP_HTTP_AUTH_TOKEN are configured.

Configuration

The server normalizes GITLAB_BASE_URL to /api/v4 automatically. If you already pass an /api/v4 URL, it is preserved.

Core settings

| Variable | Required | Default | Notes | |---|---|---:|---| | GITLAB_BASE_URL | No | https://gitlab.com | GitLab instance base URL or /api/v4 URL | | GITLAB_TOKEN | Yes | | GitLab PAT, project access token, group access token, or OAuth bearer token | | GITLAB_TOKEN_HEADER_MODE | No | bearer | Use private-token when required by some self-managed setups | | GITLAB_MCP_TOOL_PROFILE | No | readonly | Limits MCP tool discovery to a workflow profile | | GITLAB_MCP_ENABLED_TOOLS | No | empty | Comma-separated explicit tool allowlist applied after the profile | | GITLAB_MCP_DISABLED_TOOLS | No | empty | Comma-separated explicit tool denylist applied after the profile | | GITLAB_MCP_EXPOSE_DISABLED_WRITES | No | false | Compatibility override to advertise write/destructive tools even when server-side gates are disabled | | MCP_TRANSPORT | No | stdio | Use http to run Streamable HTTP when no CLI mode is provided | | MCP_HTTP_HOST | No | 127.0.0.1 | HTTP bind host | | MCP_HTTP_PORT | No | 3333 | HTTP bind port | | MCP_HTTP_PATH | No | /mcp | Streamable HTTP MCP path | | MCP_HTTP_ALLOWED_ORIGINS | No | empty | Comma-separated browser origins allowed in HTTP mode | | MCP_HTTP_ALLOWED_HOSTS | No | localhost,127.0.0.1,[::1] | Comma-separated allowed hostnames for DNS rebinding protection | | MCP_HTTP_AUTH_TOKEN | No | unset | Optional bearer token required by HTTP mode; required for non-local binds | | MCP_HTTP_ALLOW_NON_LOCALHOST | No | false | Allows non-local HTTP binds only when a bearer token is also configured | | ENABLE_WRITE_TOOLS | No | false | Enables write-capable tools | | ENABLE_DESTRUCTIVE_TOOLS | No | false | Enables destructive tools that also require per-call confirmation | | ENABLE_DRY_RUN | No | false | Returns intended write requests without mutating GitLab | | PROJECT_ALIASES | No | empty | Comma-separated alias=group/project mappings for project_id inputs | | GROUP_ALIASES | No | empty | Comma-separated alias=my-group mappings for group_id inputs |

Access controls and limits

| Variable | Default | Purpose | |---|---:|---| | PROJECT_ALLOWLIST | empty | Comma-separated project IDs or paths that are allowed | | GROUP_ALLOWLIST | empty | Comma-separated group IDs or paths that are allowed | | PROJECT_DENYLIST | empty | Comma-separated project IDs or paths that are always denied | | MAX_FILE_SIZE_BYTES | 1048576 | Maximum repository file payload | | MAX_DIFF_SIZE_BYTES | 2097152 | Maximum diff payload | | MAX_API_RESPONSE_BYTES | 4194304 | Maximum total API response payload | | GITLAB_HTTP_TIMEOUT_MS | 30000 | Request timeout |

Operational settings

| Variable | Default | Purpose | |---|---:|---| | GITLAB_USER_AGENT | gitlab-mcp-server | Custom outbound user agent | | LOG_LEVEL | info | debug, info, warn, or error | | AUDIT_LOG_PATH | unset | Optional JSON-line audit log path | | EXPOSE_SECRET_VARIABLE_VALUES | false | Keeps CI/CD secret values redacted unless explicitly enabled |

See .env.example for a complete local template.

Aliases

If you repeatedly work with the same projects or groups, you can define explicit aliases:

PROJECT_ALIASES=platform-api=platform/backend-api,storefront=commerce/storefront
GROUP_ALIASES=platform=platform,commerce=commerce

After that, any tool expecting project_id or group_id can use the alias instead of the full path. Alias resolution is explicit and local to this server configuration.

Tool profiles

The default profile is readonly, so MCP clients discover read-only tools first and disabled write/destructive tools stay hidden. Use a narrower profile when you want agents to see only the tools for a workflow:

GITLAB_MCP_TOOL_PROFILE=mr-review

Available profiles:

• readonly
• core
• mr-review
• ci-triage
• delivery
• release
• governance
• maintainer-write
• full

Explicit allow/deny lists are applied after the selected profile:

GITLAB_MCP_ENABLED_TOOLS=gitlab_get_merge_request,gitlab_get_merge_request_diff
GITLAB_MCP_DISABLED_TOOLS=gitlab_merge_merge_request

For compatibility with older broad tool discovery, set GITLAB_MCP_TOOL_PROFILE=full and GITLAB_MCP_EXPOSE_DISABLED_WRITES=true. Execution is still protected by ENABLE_WRITE_TOOLS, ENABLE_DESTRUCTIVE_TOOLS, and per-call destructive confirmation.

Guided Prompts

The server now exposes reusable MCP prompts so users do not need to memorize the full tool catalog first.

Core workflow prompts:

• gitlab_review_merge_request_workflow
• gitlab_explain_failed_pipeline_workflow
• gitlab_summarize_project_status_workflow
• gitlab_generate_weekly_delivery_summary_workflow
• gitlab_assess_project_write_safety_workflow

Hero workflow prompts:

• gitlab_stale_merge_request_cleanup_workflow
• gitlab_flaky_ci_triage_workflow
• gitlab_release_readiness_check_workflow
• gitlab_team_delivery_digest_workflow
• gitlab_portfolio_delivery_overview_workflow
• gitlab_summarize_commit_range_workflow
• gitlab_summarize_directory_workflow

Example prompt requests inside an MCP client:

Use gitlab_review_merge_request_workflow for project_id="platform-api" and merge_request_iid="42".

Use gitlab_flaky_ci_triage_workflow for project_id="platform-api" and ref="main".

These prompts point the model at the relevant gitlab_* tools for each workflow while keeping the actual data access explicit and structured.

Recommended Starting Points

If you are trying the MCP for the first time, start with the orchestration tools rather than the lower-level primitives.

Recommended first tools:

• gitlab_release_readiness_check: one-call release go/caution/hold assessment for a project
• gitlab_flaky_ci_triage: separates likely flaky CI from deterministic failures
• gitlab_stale_merge_request_cleanup: identifies stale merge requests and recommends the next action for each sampled item
• gitlab_team_delivery_digest: produces a concise project or group delivery summary plus a chat-ready status line

Example calls:

{
  "project_id": "platform-api",
  "output_format": "markdown"
}

Use that with gitlab_release_readiness_check.

{
  "project_id": "platform-api",
  "ref": "main",
  "output_format": "markdown"
}

Use that with gitlab_flaky_ci_triage.

{
  "project_id": "platform-api",
  "stale_after_days": 14,
  "output_format": "markdown"
}

Use that with gitlab_stale_merge_request_cleanup.

{
  "scope_type": "group",
  "scope_id": "platform",
  "days": 7,
  "output_format": "markdown"
}

Use that with gitlab_team_delivery_digest.

Shareable Output Formats

Selected higher-level tools support output_format="markdown" in addition to the default structured JSON response envelope.

Current markdown-capable tools:

• gitlab_summarize_project_status
• gitlab_explain_failed_pipeline
• gitlab_stale_merge_request_cleanup
• gitlab_flaky_ci_triage
• gitlab_compare_pipeline_runs
• gitlab_trace_job_to_commit_and_merge_request
• gitlab_release_readiness_check
• gitlab_team_delivery_digest
• gitlab_portfolio_delivery_overview
• gitlab_get_group_delivery_overview
• gitlab_summarize_commit_range
• gitlab_summarize_directory
• gitlab_review_merge_request_risks
• gitlab_get_merge_request_review_state
• gitlab_generate_release_notes
• gitlab_get_project_dashboard

Example calls:

{
  "project_id": "platform-api",
  "output_format": "markdown"
}

{
  "project_id": "platform-api",
  "pipeline_id": 12345,
  "output_format": "markdown"
}

{
  "scope_type": "project",
  "scope_id": "platform-api",
  "days": 7,
  "output_format": "markdown"
}

This is useful when the result is intended for chat, a GitLab comment, or a status update, while structured remains the best default for agents that want to post-process the result.

Token Setup

Recommended scopes:

• Read-only mode: read_api
• Write mode: api

Notes:

• ENABLE_WRITE_TOOLS=true only enables the MCP server's write-capable tools. It does not add GitLab permissions to the configured token.
• If write tools are enabled but GitLab returns insufficient_scope, the MCP write-mode guard has passed and the token is still missing the required GitLab scope, usually api.
• Project and group access tokens work when their scopes match the requested resources.
• Some self-managed GitLab instances work better with GITLAB_TOKEN_HEADER_MODE=private-token.
• Keep write and destructive modes off unless you explicitly need them.

Safety Model

• Read-only is the default and recommended starting point.
• The default tool profile is readonly; disabled write/destructive tools are hidden from MCP discovery.
• Write-capable tools require ENABLE_WRITE_TOOLS=true.
• Destructive tools require ENABLE_DESTRUCTIVE_TOOLS=true and confirm_destructive=true in the tool call.
• ENABLE_DRY_RUN=true lets agents inspect a write request before changing GitLab.
• Allowlists and the denylist are enforced before risky operations.
• HTTP mode is localhost-only by default and requires a bearer token before non-local binds are allowed.
• Secret CI/CD variable values remain redacted unless `EXPOSESECRETVARIABLE_VALUE

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DevquasarX9
• Source: DevquasarX9/mcp-gitlab
• License: MIT

Install and usage instructions live in the source repository linked above.