GitLab MCP

GitLab MCP is a harness-neutral Model Context Protocol server plus shared Agent Skills for GitLab repository work. Codex, Claude Code, Cline, and Pi are supported distributions of the same canonical MCP core rather than separate GitLab implementations. ChatGPT can use the same core through the remote Streamable HTTP deployment.

The project provides:

• a self-contained GitLab MCP server with typed tools;
• a general $gitlab skill;
• $gl-address-comments for unresolved merge-request discussions;
• $gl-fix-ci for pipeline and job diagnosis;
• $gl-publish for branch, commit, push, and draft-MR delivery;
• GitLab-native runner, CI lint, governance, tag, release, and pipeline schedule workflows, plus secret-safe project and group CI/CD variable management;
• thin Codex, Claude Code, Cline, and Pi distributions that reuse the same canonical core and Agent Skills; and
• stateless Streamable HTTP transport and OAuth protected-resource metadata for ChatGPT deployment.

Start here

Audience	Documentation
GitLab MCP users	User guide
Codex users	Codex adapter
Claude Code users	Claude Code adapter
Cline users	Cline adapter
Pi users	Pi adapter
Operators	Configuration reference and troubleshooting
Contributors	Developer guide and contributing guide
Deployers	ChatGPT deployment
Maintainers	Release process, publication checklist, and generalisation audit

The documentation index links the complete user, operator, developer, security, compatibility, and release documentation set.

Quick Start

For a local source installation, use Node.js 22 or newer, then build and verify the canonical MCP core:

npm.cmd ci
npm.cmd test
npm.cmd run build

Choose the adapter that matches the harness. All four supported adapters consume the same built MCP bundle and canonical Agent Skills.

For Codex, add this repository to a trusted local marketplace, install the gitlab plugin, and restart or refresh Codex. The established root Codex manifest, .mcp.json, preload, and artifact name remain supported compatibility surfaces. Configure the GitLab instance and token in the environment that launches Codex:

$env:GITLAB_URL = "https://gitlab.example.com"
$env:GITLAB_TOKEN = "<token>"

Start a new conversation and ask Codex to confirm the connection, for example:

Use GitLab to tell me which account and instance are connected.

Claude Code users can load the materialized native plugin distribution, which bundles the same MCP server and canonical Agent Skills. See the Claude Code adapter guide for package validation, --plugin-dir loading, and marketplace-compatible layout.

Cline users can use the same canonical MCP bundle over stdio and install the canonical Agent Skills without a separate GitLab implementation. See the Cline adapter guide for IDE and CLI setup.

Pi users can install the dedicated Pi package, which registers the canonical MCP tool inventory through a thin stdio bridge and exposes the same Agent Skills. See the Pi adapter guide for package installation, runtime dependency handling, and bridge limitations.

See the user guide for least-privilege token guidance, common GitLab workflows, and ChatGPT HTTP deployment.

Requirements

• Node.js 22 or newer
• a GitLab.com, GitLab Dedicated, or self-managed GitLab instance
• for local stdio use, a GitLab token with the minimum scopes required by the operations you intend to perform

Build and verify

npm.cmd install
npm.cmd test
npm.cmd run adapters:check
npm.cmd run check:bundle
npm.cmd run build
npm.cmd run validate:codex
npm.cmd run validate:claude
npm.cmd run validate:cline
npm.cmd run validate:pi
npm.cmd run check:versions
npm.cmd run check:gitlab-oauth -- https://gitlab.example.com

The canonical MCP bundle path is defined by distribution.json; the current configuration builds server/dist/gitlab-mcp.cjs. The MCP bundle itself is generated and ignored in source control, then included in release artifacts. Harness packages may still declare a harness-side runtime dependency; the Pi package, for example, uses the MCP SDK to bridge Pi to that bundled server.

distribution.json is the authoritative source for shared distribution metadata, including the neutral gitlab distribution identifier, base version, description, license, canonical MCP bundle, and Skills path. After changing it, run npm run adapters:generate and review the generated Codex/Claude Code/Cline/Pi metadata. npm run adapters:check rejects metadata drift and a missing, non-directory, or repository-escaping canonical Skills path.

npm run check:bundle performs an in-memory clean build and fails if the canonical bundle contains harness-specific implementation references. npm run check:versions verifies generated package and Codex release metadata remain aligned with distribution.json. The Codex plugin manifest may append Codex build metadata after + without changing that base distribution version. SERVER_VERSION is owned independently by the harness-neutral MCP core and is bumped only when the core runtime itself changes.

The harness-neutral core and adapter boundary are documented in ADR-001. The GEN-08 focused audit and identity decisions are recorded in docs/GENERALISATION_AUDIT.md.

Continuous integration

GitLab merge-request, default-branch, and tag pipelines run syntax checks, tests, coverage, dependency-cruiser, formatting/linting, a production dependency audit, a clean bundle build, and bundled stdio/HTTP smoke tests. GitLab SAST and secret-detection templates are also enabled. Codex, Claude Code, Cline, and Pi each have focused adapter validation after the canonical build; those jobs validate harness packaging and MCP startup without repeating the core Node/security matrix.

Tag pipelines additionally publish the deterministic Codex archive with its CycloneDX SBOM and SHA256SUMS, plus reproducible Claude Code, Cline, and Pi MCP + Skills archives with matching .sha256 sidecars, as GitLab job artifacts. The final release-set gate requires exactly the four supported harnesses and compares their canonical MCP bundle and Skills digests. Releases are not considered complete until the artifacts are verified according to docs/PUBLICATION_CHECKLIST.md.

The committed docs/gitlab-tool-contracts.json inventory invokes every registered tool with boundary-valid inputs and locks its safety classification, HTTP method, encoded route, query/body mapping, and bounded response mode. Coverage covers every production source module and fails below 90% lines, 80% functions, or 75% branches; adding a tool without an inventory entry fails the test.

The syntax and test jobs run on both node:22-alpine and node:24-alpine; the threshold-enforced coverage job runs on Node 22. The core jobs require an untagged Linux runner that can run these images and reach the npm registry. The security templates pull their analyzer images from the GitLab registry. Privileged mode is not required for the core Node.js jobs. Configure at least one project, group, or instance runner that accepts untagged jobs and permits jobs to run for at least 10 minutes before requiring successful pipelines for merge.

Local Codex authentication

Set the instance URL and token in the environment that launches Codex:

$env:GITLAB_URL = "https://gitlab.example.com"
$env:GITLAB_TOKEN = "<token>"

GITLAB_URL must use HTTPS by default and rejects embedded credentials, queries, and fragments. For an explicitly local/private development GitLab instance that cannot use TLS, set GITLAB_ALLOW_INSECURE_HTTP=true. The override is rejected in production and for public hostnames; it accepts loopback, private-network IPs, single-label hosts, and the private-development suffixes .localhost, .local, .internal, and .home.arpa.

GITLAB_URL defaults to https://gitlab.com. The Codex .mcp.json starts the bundled server over stdio and loads the thin Codex distribution adapter before the harness-neutral core. Tokens are read at runtime and are never stored in a distribution.

Use the narrowest token scopes that cover the task. Read-only work can use a read-oriented token; repository, issue, merge-request, or CI mutations require the corresponding GitLab API permissions.

Capability discovery

Call get_gitlab_capabilities before diagnosing whether a GitLab operation is unsupported, unlicensed, disabled, or merely inaccessible to the current credential. It uses only read-only requests to /user, /version, /metadata, /personal_access_tokens/self, and (when the credential is not a personal access token) /oauth/token/info. OAuth diagnostics report scopes and remaining lifetime but never expose the token or OAuth application identifier. GitLab may hide or omit these endpoints, especially on older self-managed versions or for non-administrators, so ambiguous results are reported as unknown rather than guessed.

Each capability is one of available, unavailable, permission_required, license_required, not_configured, or unknown, with a concise reason and supporting evidence where useful. Pass detailed: true for normalized per-probe outcomes, or refresh: true to bypass the cache.

Results are cached for 60 seconds per normalized instance URL and authenticated credential identity. The cache key contains a one-way SHA-256 digest, never the raw bearer token. Entries expire after 60 seconds, are bypassed by refresh, and naturally separate instances or changed credentials. Expired entries are opportunistically removed, and a 256-entry LRU limit provides a hard memory bound. The cache is in-memory only and is cleared when the MCP server process restarts.

HTTP server

For local development:

$env:MCP_PUBLIC_URL = "https://mcp.example.com/mcp"
$env:GITLAB_URL = "https://gitlab.example.com"
npm.cmd run start:http

HTTP mode requires a bearer token on every /mcp request. A server-side token is disabled by default. ALLOW_SERVER_TOKEN_HTTP=true exists only for controlled private testing and should not be used for a shared deployment.

Set MCP_READ_ONLY=true for an inspection-only deployment. In that mode the server registers only tools annotated as read-only and advertises GitLab's read_api OAuth scope. The default write-enabled mode exposes the complete tool set and requires api. The server validates every tool annotation during registration so an unclassified or mutating tool cannot silently enter the read-only surface.

When binding to the IPv4 wildcard 0.0.0.0 or IPv6 wildcard ::, set MCP_ALLOWED_HOSTS to a comma-separated allowlist of public host names. Put the service behind HTTPS and set MCP_PUBLIC_URL to its canonical public /mcp URL. Production mode requires MCP_PUBLIC_URL, rejects embedded credentials, queries, fragments, and non-/mcp paths, and requires HTTPS. MCP_ALLOW_INSECURE_PUBLIC_URL=true is available only for explicit local development on a loopback listener and is rejected in production or on a public host. ALLOW_SERVER_TOKEN_HTTP=true is likewise limited to loopback private testing and must not be used for a shared deployment.

Use the read-only get_runtime_info tool after installation or deployment to confirm the core/distribution versions, deployment mode, read-only filtering, and the deterministic SHA-256 fingerprint of the registered tool inventory.

HTTP MCP request bodies are limited to 8 MiB by default. This accommodates bounded multi-file commits and other legitimate large tool payloads while preventing unbounded request buffering. Set MCP_MAX_REQUEST_BYTES to an integer from 65,536 through 26,214,400 bytes to use a different deployment limit. Any reverse proxy in front of the server must allow at least the same request size.

Long-running HTTP deployments also bound authentication and request state:

• MCP_TOKEN_CACHE_MAX_ENTRIES limits validated bearer identities, default 256, with a 60-second TTL and LRU eviction;
• MCP_AUTH_FAILURE_LIMIT limits rejected tokens per directly connected address within MCP_AUTH_FAILURE_WINDOW_MS, default 20 failures per 60 seconds;
• MCP_AUTH_FAILURE_MAX_ENTRIES bounds failure-tracking state, default 1,024;
• MCP_MAX_CONCURRENT_REQUESTS caps active MCP requests, default 32; and
• MCP_MAX_CONCURRENT_REQUESTS_PER_IDENTITY caps requests for one validated GitLab user, default 4.

Configure complementary rate and connection limits at the TLS reverse proxy. The application deliberately uses the direct peer address rather than trusting forwarded headers by default, so proxy-level client-IP limits should be applied before traffic reaches this service.

The unauthenticated /health endpoint is a topology-free process liveness check. /ready is a separate readiness check and returns 503 when its dependency probe is unavailable. Every response includes a generated X-Request-Id; internal MCP failures log only that identifier and the error type. Embedders can provide a request-completion observer for metrics without receiving bearer tokens or request payloads.

After deploying, verify the public resource metadata and both health semantics:

npm.cmd run check:mcp-deployment -- https://mcp.example.com/mcp

Safety model

• Tools advertise read-only, write, and destructive annotations.
• create_commit supports only non-destructive file actions; deletion and forced commit updates require the separately annotated create_destructive_commit tool with concurrency-safety fields.
• GitLab response bodies, including job logs, artifacts, and API errors, are streamed under strict byte limits and remain covered by request timeouts;
• API errors are normalized without echoing credentials;
• capability discovery redacts error evidence and never reads private CI variables or mutation endpoints;
• HTTP bearer tokens are validated against the configured GitLab instance and cached by a one-way token hash in a bounded TTL/LRU cache;
• rejected credentials and concurrent requests are bounded without logging tokens or private identity details;
• HTTP mode challenges unauthenticated requests with protected-resource metadata;
• HTTP tools advertise per-tool OAuth or private server-token security schemes plus model-visible reauthorization challenges; and
• Skills require explicit intent for merge, approval, deletion, discussion resolution, and CI state changes.

License

MIT