Purpose
gitlab-mcp-server is an open-source GitLab MCP server used to connect all of GitLab's capabilities to AI assistants. It lets users make GitLab-related requests to an AI assistant in natural language, and the server calls GitLab's REST and GraphQL APIs on their behalf to complete the operations. It supports GitLab tiers (Free/CE, Premium, Ultimate), self-hosted instances, or GitLab.com (including its Orbit knowledge graph); the server detects the tier it is on and adjusts the available operation catalog. It can be used with Claude, Cursor, VS Code, Codex, and any other MCP client, and runs as a single self-contained binary.
Main capabilities and operation catalog
The server covers up to 1,098 GitLab operations, drawn from GitLab's REST and GraphQL APIs. By default it provides two dynamic discovery tools (find and execute), which are enough to reach the entire operation catalog; by comparison, listing each tool separately would cost 573,871 to 730,505 tokens. The default startup context is 11,343 tokens, and 1,941 tokens when GITLAB_MCP_CAPABILITY_SURFACE=minimal is set; this value is measured using the cl100k_base tokenizer and checked in CI. In addition to tools, it also includes 45 resources and 37 prompts.
Usage
- Authentication: You can use a personal, project, or group access token (requires the api scope; read_api can be used when GitLab accepts it), or a fine-grained token (evaluated per operation according to its authorization); HTTP mode supports OAuth. Each operation's tool reference entry states the scope and fine-grained permissions it requires.
- Client configuration: In supported environments, run it as the server command with a command such as docker, and pass the token via the GITLAB_TOKEN environment variable; the registration command itself does not carry the token, but forwards it from the environment via -e GITLAB_TOKEN. Self-hosted instances also require setting GITLAB_URL=https://gitlab.example.com；使用 For the Docker image, you also need to add -e GITLAB_URL to the docker arguments, because the container only receives explicitly listed variables. See the installation guide for per-client configuration and verification steps for each channel.
- Try it out: The public instance runs at https://mcp.jmrp.io/gitlab，浏览器检查器在 After OAuth login, calls are made in read-only mode. That instance handles tokens and all requests, so if you need long-term use, it is recommended to run it yourself.
Safeguards and surfaces
Security mechanisms include: read-only mode, safe mode (which gives a preview of each write operation instead of executing it directly), excluding tools by name, and confirmation before any destructive operation. It provides three tool surfaces (the default two discovery tools, one tool per domain, or one tool per operation) and two transports (stdio for desktop clients, or HTTP for shared deployments with credentials isolated from each other).
Releases and compliance
Releases are verifiable: signed checksums, an SBOM for each binary, and build provenance for each build artifact. The project uses the MIT license and is maintained by José M. Requena Plens; contributions are welcome on GitHub, with the contribution process in CONTRIBUTING.md, the code of conduct in CODE_OF_CONDUCT.md, and vulnerabilities reported privately according to SECURITY.md.
Use cases and limitations
Use cases include: code review (such as determining whether a merge request can be safely merged), troubleshooting pipeline failures, querying issues assigned to you, generating release notes between versions, and other everyday GitLab work. In terms of limitations: operation availability depends on the permissions of the token you hold and the instance tier; read-only mode and safe mode can restrict writes; and the hosted public instance handles tokens and requests, so it is not suitable for long-term use. The file does not provide specific pricing or fee information; its documentation site offers English and Spanish versions covering getting started, configuration, tool surfaces, HTTP server mode, security, privacy, and troubleshooting.
