gitlab-mcp-server

GitLab MCP Server

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 EXPOSE_SECRET_VARIABLE_VALUES=true.
The server does not execute shell commands. It talks directly to the GitLab REST and GraphQL APIs.

Security details: SECURITY.md and docs/security-model.md

Available Tool Areas

The server exposes concrete gitlab_* MCP tools. Representative examples:

Instance and access: gitlab_validate_token, gitlab_get_current_user, gitlab_list_accessible_projects
Projects and groups: gitlab_search, gitlab_search_projects, gitlab_search_labels, gitlab_get_project_dashboard, gitlab_get_group_delivery_overview
Repository: gitlab_get_file, gitlab_search_code, gitlab_compare_refs, gitlab_get_commit_diff
Issues: gitlab_list_issues, gitlab_create_issue, gitlab_add_issue_comment
Merge requests: gitlab_get_merge_request, gitlab_get_merge_request_commits, gitlab_get_merge_request_pipelines, gitlab_get_merge_request_review_state, gitlab_merge_merge_request
Pipelines: gitlab_list_pipelines, gitlab_explain_failed_pipeline, gitlab_find_flaky_jobs
Releases and packages: gitlab_list_releases, gitlab_create_release, gitlab_get_package
Governance: gitlab_get_project_approval_rules, gitlab_check_project_write_risk
Intelligence: gitlab_summarize_project_status, gitlab_stale_merge_request_cleanup, gitlab_flaky_ci_triage, gitlab_release_readiness_check, gitlab_team_delivery_digest, gitlab_portfolio_delivery_overview, gitlab_summarize_commit_range, gitlab_summarize_directory, gitlab_review_merge_request_risks, gitlab_generate_release_notes

Write-capable tools stay unavailable until you explicitly enable them.

For design notes and implementation details, see:

Common AI Workflows

This server is useful when you want an agent to:

inspect a GitLab repository without cloning it first
summarize a commit range and identify risky files or directories with gitlab_summarize_commit_range
understand an unfamiliar repository area with gitlab_summarize_directory
review merge request diffs, discussions, approvals, and pipeline state together
summarize recent team activity across issues, merge requests, and pipelines with gitlab_team_delivery_digest
assess cross-project portfolio health with gitlab_portfolio_delivery_overview
assess release readiness with gitlab_release_readiness_check
triage flaky CI with gitlab_flaky_ci_triage
clean up stale merge requests with gitlab_stale_merge_request_cleanup
trace a failed job back to its pipeline, commit, and merge request context
draft release notes from tags, compares, and recent delivery activity
assess whether a project is safe for AI-assisted writes before enabling write mode
produce a chat-ready delivery digest with markdown output
use guided prompts instead of manually selecting low-level tools

If you want agents and other developers to discover the right tools quickly, refer to the actual MCP tool names in prompts, examples, and client instructions.

Troubleshooting

Run gitlab-mcp-server doctor first when setup behavior is unclear.
401 Unauthorized: the token is invalid, expired, or using the wrong header mode.
403 Forbidden: the token lacks access or the resource is outside the configured allowlists.
403 insufficient_scope on write tools after ENABLE_WRITE_TOOLS=true: write mode is enabled, but the GitLab credential is still not authorized for writes. Use gitlab_validate_token or doctor; personal access tokens should show api in their scopes. For project, group, or OAuth tokens, verify the token scope and project membership directly in GitLab because PAT scope introspection may be unavailable.
404 Not Found: the resource is missing or hidden by GitLab permissions.
429 Too Many Requests: the GitLab rate limit was hit.
HTTP server refuses to start on 0.0.0.0 or another non-local host: set both MCP_HTTP_ALLOW_NON_LOCALHOST=true and MCP_HTTP_AUTH_TOKEN, then restrict MCP_HTTP_ALLOWED_HOSTS and MCP_HTTP_ALLOWED_ORIGINS to trusted values.
PAT about to expire: the doctor report and gitlab_validate_token advisory will flag short remaining lifetime when PAT introspection is available.
Large file or diff errors: raise payload limits only when you trust the workload.
CLI not found from source: run npm run build and invoke node dist/cli.js.

Development

npm ci
npm run typecheck
npm test
npm run build
npm run pack:dry-run

Supporting docs:

Publishing

This repository uses npm trusted publishing from GitHub Actions through publish.yml.

Release flow:

Update package.json version.
Commit and push.
Create and push a matching tag such as v<package-version>.
Publish a GitHub Release for that tag.
GitHub Actions publishes the package to npm through OIDC.

Manual fallback:

npm login
npm whoami
npm run clean
npm run build
npm test
npm run pack:dry-run
npm publish --access public

No NPM_TOKEN secret is required for the default GitHub Actions release path.

Published Package Contents

The npm tarball intentionally stays small and only publishes:

dist/
README.md
LICENSE
package.json