Skip to content
Back to search

gitlab-mcp

First gitlab mcp for you, building together

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/zereight/gitlab-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/zereight/gitlab-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zereight--gitlab-mcp/badge.svg)](/listings/zereight--gitlab-mcp)

HTML

<a href="/listings/zereight--gitlab-mcp"><img src="/api/listings/zereight--gitlab-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Authentication Methods

The server supports four authentication methods:

**For local/desktop use** (most common):

1. **Personal Access Token** (`GITLAB_PERSONAL_ACCESS_TOKEN`) — simplest setup 2. **OAuth2 — Local Browser** (`GITLAB_USE_OAUTH`) — recommended for better security

**For server/remote deployments**:

3. **OAuth2 — MCP Proxy** (`GITLAB_MCP_OAUTH`) — for remote MCP clients such as Claude.ai 4. **Remote Authorization** (`REMOTE_AUTHORIZATION`) — multi-user deployments where each caller provides their own token

Quick setup paths

- **Claude Code**: see [Claude Code Setup Guide](./docs/clients/claude-code.md) - **VS Code**: see [VS Code Setup Guide](./docs/clients/vscode.md) - **GitHub Copilot**: see [GitHub Copilot Setup Guide](./docs/clients/copilot.md) - **Codex**: see [Codex Setup Guide](./docs/clients/codex.md) - **Cursor**: see [Cursor Setup Guide](./docs/clients/cursor.md) - **Factory AI Droid / OpenClaw / OpenCode style clients**: see [JSON-Based MCP Clients Setup Guide](./docs/clients/json-clients.md) - **OAuth browser flow details**: see [OAuth2 Authentication Setup Guide](./docs/auth/oauth-setup.md) - **OAuth without a localhost callback** (SSO, remote shell, background clients): run `zereight-mcp-gitlab auth` (GitLab 17.9+ device flow; 17.2–17.8 need `oauth2_device_grant_flow`), then start the server with `GITLAB_USE_OAUTH=true`. See [standalone device-flow command](./docs/auth/oauth-setup.md#standalone-device-flow-auth-command).

For the simplest local setup, start with a Personal Access Token. For browser-based local auth, use OAuth2. For remote or multi-user deployments, continue to the MCP OAuth and Remote Authorization sections later in this README.

Install the server once:

brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp
brew install zereight/gitlab-mcp/zereight-mcp-gitlab

Or with npm:

npm install -g @zereight/mcp-gitlab

Or with Nix, by adding this flake to your own:

# flake.nix
inputs.gitlab-mcp.url = "github:zereight/gitlab-mcp";

# wherever you configure your MCP client:
command = lib.getExe inputs.gitlab-mcp.packages.${system}.default;

The store path is pinned by your lock file; update it with `nix flake update gitlab-mcp`.

The examples use `zereight-mcp-gitlab`, a less collision-prone alias for the legacy `mcp-gitlab` binary. If your MCP client cannot find it, use the absolute path from `which zereight-mcp-gitlab`.

No global install? Pin `npx` to the previous stable release (the version these docs recommend), for example `npx -y @zereight/mcp-gitlab@2.1.68`. If you always want the newest release, use `npx -y @zereight/mcp-gitlab@latest` instead. The server prints a notice to stderr on startup when a newer version is available (disable with `GITLAB_DISABLE_VERSION_CHECK=true`).

Using CLI Arguments (for clients with env var issues)

Some MCP clients (like GitHub Copilot CLI) have issues with environment variables. Use CLI arguments instead:

{
  "mcpServers": {
    "gitlab": {
      "command": "zereight-mcp-gitlab",
      "args": ["--token=YOUR_GITLAB_TOKEN", "--api-url=https://gitlab.com/api/v4"],
      "tools": ["*"]
    }
  }
}

**Available CLI arguments:**

- `--token` - GitLab Personal Access Token (replaces `GITLAB_PERSONAL_ACCESS_TOKEN`) - `--api-url` - GitLab API URL (replaces `GITLAB_API_URL`) - `--read-only=true` - Enable read-only mode (replaces `GITLAB_READ_ONLY_MODE`, deprecated — prefer `--permission-mode=readonly`) - `--permission-mode` - Permission level: `readonly`, `modify` (no delete or teardown tools), or `full` (replaces `GITLAB_PERMISSION_MODE`, default `full`) - `--use-wiki=true` - Enable wiki API (replaces `USE_GITLAB_WIKI`, legacy — prefer `GITLAB_TOOLSETS=wiki`) - `--use-milestone=true` - Enable milestone API (replaces `USE_MILESTONE`, legacy — prefer `GITLAB_TOOLSETS=milestones`)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,129 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="assets/logo.png" alt="GitLab MCP" width="160">
  3. </p>
  4. # GitLab MCP Server
  5. [![GitHub stars](https://badgen.net/github/stars/zereight/gitlab-mcp?icon=github&label=Star)](https://github.com/zereight/gitlab-mcp)
  6. [![npm downloads](https://badgen.net/npm/dm/@zereight/mcp-gitlab)](https://www.npmjs.com/package/@zereight/mcp-gitlab)
  7. [![npm](https://img.shields.io/npm/v/@zereight/mcp-gitlab.svg)](https://www.npmjs.com/package/@zereight/mcp-gitlab)
  8. [![GitHub License](https://badgen.net/github/license/zereight/gitlab-mcp)](https://github.com/zereight/gitlab-mcp/blob/main/LICENSE)
  9. [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/zereight/gitlab-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/zereight/gitlab-mcp)
  10. [![CodeQL](https://github.com/zereight/gitlab-mcp/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/zereight/gitlab-mcp/actions/workflows/codeql.yml?query=branch%3Amain)
  11. [![Live API Tests](https://github.com/zereight/gitlab-mcp/actions/workflows/live-tests.yml/badge.svg?branch=main)](https://github.com/zereight/gitlab-mcp/actions/workflows/live-tests.yml?query=branch%3Amain)
  12. [![Ask DeepWiki](https://img.shields.io/badge/DeepWiki-Ask-blue)](https://deepwiki.com/zereight/gitlab-mcp)
  13. [![MCP Toplist](https://mcptoplist.com/badge/io.github.zereight%2Fgitlab-mcp.svg)](https://mcptoplist.com/server/io.github.zereight%2Fgitlab-mcp)
  14. [![mcpindex](https://mcpindex.ai/api/v1/badge/io-github-zereight-gitlab-mcp)](https://mcpindex.ai/server/io-github-zereight-gitlab-mcp)
  15. [English](./README.md) | [한국어](./README.ko.md) | [简体中文](./README.zh-CN.md) | [Português (Brasil)](./README.pt-BR.md)
  16. 📖 **[Documentation →](https://zereight.github.io/gitlab-mcp/)** · [llms.txt](./llms.txt) · [llms-full.txt](./llms-full.txt)
  17. **Default: 40 tools** (38 `core` + `discover_tools` + `help`). 290 tools exist in total (287 in toolsets + `execute_graphql` + `discover_tools` + `help`). Start lean; call `discover_tools` to activate more for this session.
  18. > **Token budget:** MCP clients send the whole `tools/list` to the model at session start. Keep the default (~40 tools, ~12k schema tokens). Call `discover_tools` to activate a category for this session (session-only; with `OAUTH_STATELESS_MODE=true` persist a named `GITLAB_TOOLSETS` list), or use [Skill + CLI](./docs/getting-started/cli-without-mcp.md) and skip MCP schemas. **Do not set `GITLAB_TOOLSETS=all`** — it loads ~all tools and costs ~73k schema tokens. See [tools/list size](#toolslist-size-measured-2026-11-14) and [comparison](./docs/comparison/index.md).
  19. Install the `zereight-mcp-gitlab` binary first with `npm install -g @zereight/mcp-gitlab`, or Homebrew `brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp` and `brew install zereight/gitlab-mcp/zereight-mcp-gitlab`. Official MCP Registry listing: [`io.github.zereight/gitlab-mcp`](https://registry.modelcontextprotocol.io/?q=io.github.zereight%2Fgitlab-mcp). One-liner: `npx -y @zereight/mcp-gitlab@latest`.
  20. ### Without → With
  21. | Without this MCP | With this MCP |
  22. | ---------------- | ------------- |
  23. | Paste MR URLs and diffs into chat | `list_merge_request_changed_files` → batched `get_merge_request_file_diff` |
  24. | Hunt job logs in the GitLab UI | `get_pipeline_job_output` with pagination |
  25. | Re-explain the project path every turn | `project_id=group%2Fproject` and `merge_request_iid=123` |
  26. ### Three install paths
  27. | Path | When | How |
  28. | ---- | ---- | --- |
  29. | Local IDE | Cursor, Claude Code, Codex on your machine | stdio + PAT or local OAuth |
  30. | Shared HTTP | Team or hosted MCP | Streamable HTTP URL + remote auth or MCP OAuth |
  31. | Claude.ai | Claude web connectors | Public HTTPS + `GITLAB_MCP_OAUTH` |
  32. ### Install
  33. [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=zereight.gitlab-mcp&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB6ZXJlaWdodC9tY3AtZ2l0bGFiQGxhdGVzdCJdLCJlbnYiOnsiR0lUTEFCX1BFUlNPTkFMX0FDQ0VTU19UT0tFTiI6IiR7ZW52OkdJVExBQl9QRVJTT05BTF9BQ0NFU1NfVE9LRU59IiwiR0lUTEFCX0FQSV9VUkwiOiJodHRwczovL2dpdGxhYi5jb20vYXBpL3Y0In19)
  34. Install the binary first (`npm install -g @zereight/mcp-gitlab`, or Homebrew `brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp` then `brew install zereight/gitlab-mcp/zereight-mcp-gitlab`). Read the token without echo:
  35. ```bash
  36. read -rs GITLAB_PERSONAL_ACCESS_TOKEN && export GITLAB_PERSONAL_ACCESS_TOKEN
  37. ```
  38. ```bash
  39. # Claude Code
  40. claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
  41. # Codex
  42. codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
  43. ```
  44. Other clients: [VS Code](./docs/clients/vscode.md) · [GitHub Copilot](./docs/clients/copilot.md) · [JSON clients](./docs/clients/json-clients.md) · [Cursor details](./docs/clients/cursor.md)
  45. ### Agent paste-prompt
  46. Copy this into an agent that can edit MCP config:
  47. ```
  48. Install the GitLab MCP server (@zereight/mcp-gitlab) for this workspace.
  49. Binary: zereight-mcp-gitlab (npm i -g @zereight/mcp-gitlab, or npx -y @zereight/mcp-gitlab@latest).
  50. Auth: GITLAB_PERSONAL_ACCESS_TOKEN plus GITLAB_API_URL=https://gitlab.com/api/v4 (or GITLAB_USE_OAUTH=true).
  51. Local: claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
  52. Or: codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
  53. Cursor: use the README deeplink or docs/clients/cursor.md.
  54. Remote HTTP: point the client at https://mcp.example.com/mcp (Streamable HTTP). Claude.ai needs GITLAB_MCP_OAUTH on that host.
  55. Default list: 40 tools (38 core + discover_tools + help). Call discover_tools to expand. Do not set GITLAB_TOOLSETS=all (loads ~all schemas, ~73k tokens). Do not enable the api toolset unless you accept its bypass risk.
  56. Equal non-MCP path: npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill plus the zereight-mcp-gitlab CLI.
  57. ```
  58. ### Remote HTTP
  59. First-class option for a hosted or self-hosted server. Point the client at a Streamable HTTP URL:
  60. ```json
  61. {
  62. "mcpServers": {
  63. "gitlab": {
  64. "type": "http",
  65. "url": "https://mcp.example.com/mcp"
  66. }
  67. }
  68. }
  69. ```
  70. - Hosted / Claude.ai: `GITLAB_MCP_OAUTH=true` on the server (see [MCP OAuth](#mcp-oauth-setup-claudeai-native-oauth))
  71. - Per-user PAT headers: `REMOTE_AUTHORIZATION=true` (see [Remote Authorization](#using-remote-authorization-remote_authorization))
  72. - Local Docker examples are in [Usage](#usage)
  73. ### Skill + CLI (no MCP required)
  74. Skill + CLI is an equal path, not a fallback. Same workflows, full payloads in a terminal, no MCP registration.
  75. ```bash
  76. npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill
  77. zereight-mcp-gitlab user whoami
  78. zereight-mcp-gitlab mr list
  79. ```
  80. See [CLI without MCP](./docs/getting-started/cli-without-mcp.md) and [`skills/gitlab-mcp/`](./skills/gitlab-mcp/).
  81. ### MCP vs Human CLI
  82. | Use MCP when | Use the CLI when |
  83. | ------------ | ---------------- |
  84. | The agent needs structured tools in chat | You need the full payload (diffs, logs, artifacts) |
  85. | `jmespath` or compact results are enough | `GITLAB_MCP_COMPACT_RESULTS` is on and you want the rest in a terminal |
  86. | You already registered the server | You have a PAT or ran `auth` and do not want MCP |
  87. Human CLI is never compacted. Destructive tools and `GITLAB_TOOL_POLICY_APPROVE` tools need `--yes`.
  88. ### Tips
  89. `project_id` is a numeric ID or a URL-encoded path. Example: group `group`, project `project`, merge request `!123` → `project_id=group%2Fproject`, `merge_request_iid=123`. Nested groups use `%2F` between every segment (`group%2Fsubgroup%2Fproject`).
  90. ### FAQ
  91. **How do I authenticate?** Local desktop: `GITLAB_PERSONAL_ACCESS_TOKEN` (or `GITLAB_PERSONAL_ACCESS_TOKEN_FILE`) is the simplest. Local OAuth is `GITLAB_USE_OAUTH=true`. Remote Claude.ai uses `GITLAB_MCP_OAUTH`. Multi-user HTTP uses `REMOTE_AUTHORIZATION` and a per-request token header.
  92. **Why do I only see ~40 tools?** The default `core` toolset is 38 tools plus always-on `discover_tools` and `help`. That is intentional: a client sends every listed schema to the model up front. Call `discover_tools` with no args to list categories, then pass a category (`pipelines`, `wiki`, …) to activate it for this session. Session-only; with `OAUTH_STATELESS_MODE=true` persist a named `GITLAB_TOOLSETS` list. **Do not set `GITLAB_TOOLSETS=all`** — it loads ~all schemas (~73k tokens) and still does **not** enable `api`.
  93. **Local OAuth vs MCP OAuth vs remote auth?** Local OAuth opens a browser on the same machine as the server. MCP OAuth is for a public HTTPS server and clients such as Claude.ai. Remote authorization forwards the caller's PAT or job token; there is no OAuth dance.
  94. **How do I shrink huge replies?** Pass `jmespath` on any tool call. Or set `GITLAB_MCP_COMPACT_RESULTS=true` so oversized MCP replies become a preview plus a CLI command. Use the CLI when you need the full payload.
  95. **Why is the `api` toolset dangerous?** `gitlab_api_request` bypasses group/project allowlists, other tool filters, and per-tool safety checks. Prompt injection can drive it. Enable it only by listing `api` in `GITLAB_TOOLSETS`. `all`, `discover_tools`, and `GITLAB_TOOLS` do not.
  96. ### Cursor rule / CLAUDE.md snippet
  97. ```
  98. GitLab merge requests, issues, and pipelines go through this MCP (@zereight/mcp-gitlab).
  99. Start with the default core tools. Call discover_tools to expand. Do not set GITLAB_TOOLSETS=all.
  100. Prefer list_merge_request_changed_files, then batched get_merge_request_file_diff.
  101. Use jmespath or compact results; use the CLI for full diffs and job logs.
  102. ```
  103. [![Star History Chart](./assets/star-history.png)](https://www.star-history.com/?repos=zereight%2Fgitlab-mcp&type=date&legend=top-left)
  104. ## @zereight/mcp-gitlab
  105. **Agent-workflow-optimized GitLab MCP** — manage projects, merge requests, issues, pipelines, wiki, releases, tags, milestones, and more through stdio, SSE, and Streamable HTTP.
  106. Supports PAT, OAuth, read-only mode, dynamic API URLs, and remote authorization for VS Code, Claude, Cursor, Copilot, and other MCP clients.
  107. ### Why use this GitLab MCP?
  108. - **Default 40 tools (38 `core` + `discover_tools` + `help`); 290 total** — start lean; call `discover_tools` to activate more without CQRS-style grouping. `GITLAB_TOOLSETS=all` loads ~all schemas (~73k tokens); prefer discover-on-demand or Skill + CLI
  109. - **MR 2-step review** — `list_merge_request_changed_files` → batched `get_merge_request_file_diff`
  110. - **Agent Skill built in** — workflow guidance in `skills/gitlab-mcp/`
  111. - **Flexible auth** — Personal Access Token, local OAuth2 browser flow, MCP OAuth proxy, and per-request remote authorization
  112. - **Multiple transports** — stdio for local clients, SSE for legacy clients, and Streamable HTTP for modern remote deployments
  113. - **Client-friendly setup** — examples for Claude Code, Codex, Antigravity, OpenCode, Copilot, Cline, Roo Code, Cursor, Kilo Code, and Amp Code
  114. - **Self-hosted ready** — works with custom GitLab instances, proxy settings, and dynamic API URL routing
  115. - **JMESPath result filtering** — optional `jmespath` on tool calls (see `tools/list`) shrinks JSON results without changing GitLab API requests; when response masking is enabled, JMESPath runs on masked data.
  116. ### How we compare
  117. | | @zereight/mcp-gitlab | GitLab MCP A (community CQRS-style) | GitLab official MCP server |
  118. | -------------- | ----------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
  119. | **Best for** | AI agent workflows | Enterprise multi-instance / grouped tools | Built into GitLab, no separate install |
  120. | **Tool model** | 290 tools: 287 in toolsets + `execute_graphql` + `discover_tools` + `help` | ~50–60 grouped `browse_*` / `manage_*` tools | Toolsets chosen with an HTTP header |
  121. | **MR review** | 2-step batched diff | Varies | `get_merge_request` with diffs |
  122. | **Node.js** | >=20.0.0 | Often >=24 | Node.js 20+ for stdio via `mcp-remote` |
  123. | **License** | MIT | Varies | Part of GitLab |
  124. ### tools/list size (measured 2026-11-14)
  125. A client sends the whole `tools/list` result to the model at session start. Token estimate is UTF-8 bytes / 4.
  126. | Profile | Tools | JSON bytes | Est. tokens |
  127. | ------- | ----: | ---------: | ----------: |
  128. | Default (`core` + `discover_tools` + `help`) | 40 | 47,822 | 11,956 |
  129. | `GITLAB_TOOL_PROFILE=slim` | 39 | 46,814 | 11,704 |
  130. | `GITLAB_TOOLSETS=all` | 286 | 295,933 | 73,984 |
  131. Re-measure with `npm run build && npm run test:mock` (`test/tools-list-budget.test.ts`) after description or schema changes.
  132. GitLab also ships an [official MCP server](https://docs.gitlab.com/user/model_context_protocol/mcp_server/).
  133. - Free, Premium, and Ultimate. Moved from Premium to Free in GitLab 19.2. Generally available in GitLab 19.5.
  134. - On GitLab.com, a top-level group Owner allows access to the MCP server. On GitLab Self-Managed and GitLab Dedicated, an administrator controls the instance setting. Default rules are on the official page.
  135. - Remote clients use HTTP `https://<gitlab.example.com>/api/v4/mcp` with OAuth 2.0 dynamic client registration.
  136. - stdio goes through `mcp-remote` and needs Node.js 20 or later.
  137. - Toolsets use the `X-Gitlab-Enabled-Mcp-Server-Toolsets` header. An optional `X-Gitlab-Mcp-Server-Tool-Name-Prefix` header keeps the first 32 characters of a tool-name prefix.
  138. [Full comparison with the official GitLab MCP server →](./docs/comparison/official-gitlab-mcp.md)
  139. Quick start: choose either Personal Access Token or OAuth2 setup below, install `@zereight/mcp-gitlab`, and use `zereight-mcp-gitlab` in your MCP client configuration.
  140. ### Client Setup Guides
  141. - [Claude Code Setup Guide](./docs/clients/claude-code.md)
  142. - [VS Code Setup Guide](./docs/clients/vscode.md)
  143. - [GitHub Copilot Setup Guide](./docs/clients/copilot.md)
  144. - [Codex Setup Guide](./docs/clients/codex.md)
  145. - [Cursor Setup Guide](./docs/clients/cursor.md)
  146. - [JSON-Based MCP Clients Setup Guide](./docs/clients/json-clients.md) - for Factory AI Droid, OpenClaw, and OpenCode style clients
  147. - [OAuth2 Authentication Setup Guide](./docs/auth/oauth-setup.md)
  148. - [Environment Variables Reference](./docs/configuration/environment-variables.md)
  149. - [Stateless Mode — Multi-Pod HPA](./docs/configuration/stateless-mode.md)
  150. - [Custom Agents and Multiple PAT Setup](./docs/auth/custom-agent-multiple-pat.md)
  151. ## Usage
  152. ### Setup Overview
  153. #### Authentication Methods
  154. The server supports four authentication methods:
  155. **For local/desktop use** (most common):
  156. 1. **Personal Access Token** (`GITLAB_PERSONAL_ACCESS_TOKEN` or `GITLAB_PERSONAL_ACCESS_TOKEN_FILE`) — simplest setup
  157. 2. **OAuth2 — Local Browser** (`GITLAB_USE_OAUTH`) — recommended for better security
  158. **For server/remote deployments**:
  159. 3. **OAuth2 — MCP Proxy** (`GITLAB_MCP_OAUTH`) — for remote MCP clients such as Claude.ai
  160. 4. **Remote Authorization** (`REMOTE_AUTHORIZATION`) — multi-user deployments where each caller provides their own token
  161. #### Quick setup paths
  162. - **Claude Code**: see [Claude Code Setup Guide](./docs/clients/claude-code.md)
  163. - **VS Code**: see [VS Code Setup Guide](./docs/clients/vscode.md)
  164. - **GitHub Copilot**: see [GitHub Copilot Setup Guide](./docs/clients/copilot.md)
  165. - **Codex**: see [Codex Setup Guide](./docs/clients/codex.md)
  166. - **Cursor**: see [Cursor Setup Guide](./docs/clients/cursor.md)
  167. - **Factory AI Droid / OpenClaw / OpenCode style clients**: see [JSON-Based MCP Clients Setup Guide](./docs/clients/json-clients.md)
  168. - **OAuth browser flow details**: see [OAuth2 Authentication Setup Guide](./docs/auth/oauth-setup.md)
  169. - **OAuth without a localhost callback** (SSO, remote shell, background clients): run `zereight-mcp-gitlab auth` (GitLab 17.9+ device flow; 17.2–17.8 need `oauth2_device_grant_flow`), then start the server with `GITLAB_USE_OAUTH=true`. See [standalone device-flow command](./docs/auth/oauth-setup.md#standalone-device-flow-auth-command).
  170. For the simplest local setup, start with a Personal Access Token. For browser-based local auth, use OAuth2. For remote or multi-user deployments, continue to the MCP OAuth and Remote Authorization sections later in this README.
  171. Install the server once:
  172. ```shell
  173. brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp
  174. brew install zereight/gitlab-mcp/zereight-mcp-gitlab
  175. ```
  176. Or with npm:
  177. ```shell
  178. npm install -g @zereight/mcp-gitlab
  179. ```
  180. Or with Nix, by adding this flake to your own:
  181. ```nix
  182. # flake.nix
  183. inputs.gitlab-mcp.url = "github:zereight/gitlab-mcp";
  184. # wherever you configure your MCP client:
  185. command = lib.getExe inputs.gitlab-mcp.packages.${system}.default;
  186. ```
  187. The store path is pinned by your lock file; update it with `nix flake update gitlab-mcp`.
  188. The examples use `zereight-mcp-gitlab`, a less collision-prone alias for the legacy `mcp-gitlab` binary. If your MCP client cannot find it, use the absolute path from `which zereight-mcp-gitlab`.
  189. No global install? Pin `npx` to the previous stable release (the version these docs recommend), for example `npx -y @zereight/mcp-gitlab@2.3.28`. If you set `GITLAB_MASKING_ENABLED`, use 2.3.29 or later (or `@latest`): older releases return the values of CI/CD variables that GitLab flags masked or hidden in plain text. If you always want the newest release, use `npx -y @zereight/mcp-gitlab@latest` instead. To try a fix merged to `main` before the next stable release, use `npx -y @zereight/mcp-gitlab@next`, a pre-release build that is not meant for production. The server prints a notice to stderr on startup when a newer version is available (disable with `GITLAB_DISABLE_VERSION_CHECK=true`).
  190. #### Claude Desktop one-click install (MCP Bundle)
  191. Every GitHub release after v2.3.1 ships a `gitlab-mcp.mcpb` [MCP Bundle](https://github.com/modelcontextprotocol/mcpb). Download the [latest bundle](https://github.com/zereight/gitlab-mcp/releases/latest/download/gitlab-mcp.mcpb) and open it with Claude Desktop (or drag it into **Settings → Extensions**). Claude Desktop asks for your Personal Access Token (stored as a sensitive value) and lets you set `GITLAB_API_URL`, `GITLAB_PERMISSION_MODE`, `GITLAB_TOOLSETS`, and `GITLAB_MASKING_ENABLED`. No separate Node.js or npm install is needed.
  192. To build the bundle from source, run `npm run pack:mcpb` (writes `gitlab-mcp.mcpb`).
  193. #### Using CLI Arguments (for clients with env var issues)
  194. Some MCP clients (like GitHub Copilot CLI) have issues with environment variables. Use CLI arguments instead:
  195. ```json
  196. {
  197. "mcpServers": {
  198. "gitlab": {
  199. "command": "zereight-mcp-gitlab",
  200. "args": ["--token=YOUR_GITLAB_TOKEN", "--api-url=https://gitlab.com/api/v4"],
  201. "tools": ["*"]
  202. }
  203. }
  204. }
  205. ```
  206. **Available CLI arguments:**
  207. - `--token` - GitLab Personal Access Token (replaces `GITLAB_PERSONAL_ACCESS_TOKEN`)
  208. - `--api-url` - GitLab API URL (replaces `GITLAB_API_URL`)
  209. - `--read-only=true` - Deprecated (removed in next major (v3.0.0)); use `--permission-mode=readonly` instead (replaces `GITLAB_READ_ONLY_MODE`)
  210. - `--permission-mode` - Permission level: `readonly`, `modify` (no delete or teardown tools), or `full` (replaces `GITLAB_PERMISSION_MODE`, default `full`)
  211. - `--toolsets` - Named toolsets (replaces `GITLAB_TOOLSETS`; unset uses the lean `core` default). Do not pass `all` unless you accept ~73k schema tokens. `gitlab_api_request` needs `--toolsets=api`
  212. - `--tools=list_issues` - Add individual tools (replaces `GITLAB_TOOLS`)
  213. - `--use-wiki=true` - Deprecated (removed in next major (v3.0.0)); use `--toolsets=core,wiki` instead (replaces `USE_GITLAB_WIKI`)
  214. - `--use-milestone=true` - Deprecated (removed in next major (v3.0.0)); use `--toolsets=core,milestones` instead (replaces `USE_MILESTONE`)
  215. - `--use-pipeline=true` - Deprecated (removed in next major (v3.0.0)); use `--toolsets=core,pipelines` and append `validate_ci_lint,validate_project_ci_lint` to the existing `--tools` list (or set `--tools=validate_ci_lint,validate_project_ci_lint` when that list is unset) (replaces `USE_PIPELINE`)
  216. - `--disable-version-check=true` - Disable the startup new-version notice (replaces `GITLAB_DISABLE_VERSION_CHECK`)
  217. - `--masking-enabled=true` - Enable text-response masking (replaces `GITLAB_MASKING_ENABLED`)
  218. - `--masking-config` - Path to a masking configuration file (replaces `GITLAB_MASKING_CONFIG`)
  219. - `--masking-policy-file` - Path to a protected managed-policy file (replaces `GITLAB_MASKING_POLICY_FILE`)
  220. - `--masking-workspace-dir` - Directory used to resolve masking files (replaces `GITLAB_MASKING_WORKSPACE_DIR`)
  221. - `--download-dir` - Directory `download_attachment` and `download_job_artifacts` save files under (replaces `GITLAB_DOWNLOAD_DIR`; default `.gitlab-mcp-downloads`)
  222. - `--compact-results=true` - Truncate oversized MCP tool replies and attach a CLI command for the full payload (replaces `GITLAB_MCP_COMPACT_RESULTS`; default off)
  223. - `--compact-result-chars` - Character threshold for compacting (replaces `GITLAB_MCP_COMPACT_RESULT_CHARS`; default `4000`)
  224. - `--compact-tools` - Comma-separated tool names to compact when oversized, without turning global compact on (replaces `GITLAB_MCP_COMPACT_TOOLS`)
  225. - `--list-summary-default=true` - `list_*` tools and `mr_discussions` treat an omitted `summary` argument as `true`; `summary: false` still returns the full JSON (replaces `GITLAB_MCP_LIST_SUMMARY_DEFAULT`; default off)
  226. - `--audit-log=true` - Opt-in NDJSON audit log of MCP tool calls for SIEM ingestion (replaces `GITLAB_AUDIT_LOG`; default off)
  227. - `--audit-log-file` - Append audit lines to this file; unset writes NDJSON to stderr, never stdout (replaces `GITLAB_AUDIT_LOG_FILE`)
  228. - `--tool-profile` - `full` (default) or `slim`. `slim` drops draft notes, emoji reactions, labels, CI catalog tools, and `create_group` from the initial list. Ignored when `GITLAB_TOOLSETS` is set (replaces `GITLAB_TOOL_PROFILE`)
  229. If you already set `GITLAB_TOOLSETS` or `--toolsets`, append `wiki`, `milestones`, or `pipelines` to that list instead of replacing it. If you already set `GITLAB_TOOLS` or `--tools`, append `validate_ci_lint` and `validate_project_ci_lint` to that list instead of replacing it. An explicit list replaces the default `core` toolset; it does not merge.
  230. CLI arguments take precedence over environment variables.
  231. `zereight-mcp-gitlab auth` is a subcommand (not an MCP server flag). It runs GitLab device flow and exits. See [CLI Arguments](./docs/getting-started/cli-arguments.md#auth).
  232. The same binary is also a `gh`-style GitLab CLI (`tool <name>` or curated forms such as `mr list`). **No MCP registration is needed** — set a PAT, or run `auth` and set `GITLAB_USE_OAUTH=true`: see [CLI without MCP](./docs/getting-started/cli-without-mcp.md). `setup --cursor` / `setup --claude` prints client config; `doctor` checks token, API URL, toolsets, and version. Use it for the full payload in a terminal. MCP replies stay in the chat unless you set `GITLAB_MCP_COMPACT_RESULTS=true` (or `--compact-results`), which replaces oversized tool replies with a preview and a CLI command. Human CLI is never compacted. Same permission mode, toolsets, denied-tools regex, and tool-policy filters. Destructive tools and `GITLAB_TOOL_POLICY_APPROVE` tools need `--yes`. See [Human CLI](./docs/getting-started/cli-arguments.md#human-cli).
  233. > **Fine-grained tool filtering:** use `GITLAB_PERMISSION_MODE=modify` to allow create/update while
  234. > blocking every delete tool and the destructive teardown tools (`cancel_pipeline`,
  235. > `cancel_pipeline_job`, `stop_environment`, `stop_stale_environments`, `unprotect_branch`,
  236. > `unprotect_tag`) —
  237. > including destructive mutations (deletion and teardown verbs) through `execute_graphql` and
  238. > `push_files` `delete`/`move` actions — or `GITLAB_PERMISSION_MODE=readonly` for read-only
  239. > access. You can also
  240. > enable toolset groups with `GITLAB_TOOLSETS=<group,…>`, allow-list individual tools with
  241. > `GITLAB_TOOLS=<tool,…>` (e.g. read-only groups plus a few specific write tools), and
  242. > deny-list by pattern with `GITLAB_DENIED_TOOLS_REGEX`. The legacy `USE_GITLAB_WIKI` /
  243. > `USE_MILESTONE` / `USE_PIPELINE` flags are deprecated (removed in next major (v3.0.0)).
  244. > Use `GITLAB_TOOLSETS=core,wiki`, `core,milestones`, or `core,pipelines`
  245. > (`USE_PIPELINE` also needs `validate_ci_lint,validate_project_ci_lint` appended to an existing `GITLAB_TOOLS` list instead of replacing it).
  246. > If you already set `GITLAB_TOOLSETS`, append the toolset to your existing list instead of replacing it.
  247. > If `GITLAB_TOOLS` is unset, set `GITLAB_TOOLS=validate_ci_lint,validate_project_ci_lint`. If it is already set, append `validate_ci_lint,validate_project_ci_lint` instead of replacing that list.
  248. > See [Tools Reference](./docs/tools/index.md#feature-toggles) and
  249. > [Environment Variables](./docs/configuration/environment-variables.md).
  250. > [!CAUTION]
  251. > `gitlab_api_request` (toolset `api`) bypasses `GITLAB_ALLOWED_GROUPS` and other group restrictions, project allowlists, tool-level restrictions (`GITLAB_TOOLS`, `GITLAB_DENIED_TOOLS_REGEX` on other tools), and individual tool safety checks. The full token permission scope is exposed. Prompt injection can drive this tool. Operators who rely on these restrictions must NOT enable it.
  252. > Enable it only by listing `api` in `GITLAB_TOOLSETS` (`GITLAB_TOOLSETS=all`, `discover_tools`, `GITLAB_TOOLS`, legacy `USE_*` flags, and `GITLAB_TOOL_PROFILE` do not). With `GITLAB_ALLOWED_PROJECT_IDS` or a session project scope, only `/projects/:id` paths for an allowed project are accepted. Endpoints such as `/search`, `/users`, `/groups/:id`, and `/runners` are rejected. Body and query parameters that name another project are not checked. `GITLAB_PROJECT_ID` and OAuth group allowlists are not enforced.
  253. - sse
  254. Pass the variable name only. The Docker client copies the exported `GITLAB_PERSONAL_ACCESS_TOKEN` into the container.
  255. ```shell
  256. docker run -i --rm \
  257. -e HOST=0.0.0.0 \
  258. -e GITLAB_PERSONAL_ACCESS_TOKEN \
  259. -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  260. -e GITLAB_PERMISSION_MODE=readonly \
  261. -e GITLAB_TOOLSETS=core,wiki,milestones,pipelines \
  262. -e SSE=true \
  263. -e SSE_AUTH_TOKEN=your_mcp_sse_token \
  264. -p 3333:3002 \
  265. zereight050/gitlab-mcp
  266. ```
  267. ```json
  268. {
  269. "mcpServers": {
  270. "gitlab": {
  271. "type": "sse",
  272. "url": "http://localhost:3333/sse",
  273. "headers": {
  274. "Authorization": "Bearer your_mcp_sse_token"
  275. }
  276. }
  277. }
  278. }
  279. ```
  280. - streamable-http
  281. ```shell
  282. docker run -i --rm \
  283. -e HOST=0.0.0.0 \
  284. -e REMOTE_AUTHORIZATION=true \
  285. -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  286. -e GITLAB_PERMISSION_MODE=readonly \
  287. -e GITLAB_TOOLSETS=core,wiki,milestones,pipelines \
  288. -e STREAMABLE_HTTP=true \
  289. -p 3333:3002 \
  290. zereight050/gitlab-mcp
  291. ```
  292. ```json
  293. {
  294. "mcpServers": {
  295. "gitlab": {
  296. "type": "streamable-http",
  297. "url": "http://localhost:3333/mcp",
  298. "headers": {
  299. "Authorization": "Bearer glpat-..."
  300. }
  301. }
  302. }
  303. }
  304. ```
  305. #### Using MCP OAuth Proxy (`GITLAB_MCP_OAUTH`)
  306. > **For server/remote deployments only.** This mode requires the MCP server to be deployed with a publicly accessible HTTPS URL. For local/desktop use, see `GITLAB_USE_OAUTH` above.
  307. For remote MCP clients that support the MCP OAuth specification (e.g. Claude.ai).
  308. The server acts as a full OAuth 2.0 authorization server — unauthenticated requests
  309. receive a `401 + WWW-Authenticate` response, which triggers the OAuth browser flow
  310. automatically on the client side.
  311. Remote MCP clients such as OpenCode, MCPJam, and Claude.ai can send their own
  312. callback URL during authorization. If you cannot register every client callback
  313. URL in GitLab, enable `GITLAB_OAUTH_CALLBACK_PROXY=true`. With callback proxy
  314. mode, GitLab only needs one registered redirect URI: `{MCP_SERVER_URL}/callback`.
  315. `GITLAB_OAUTH_REDIRECT_URI` is for local OAuth (`GITLAB_USE_OAUTH`) only. It does
  316. not override remote MCP OAuth client callback URLs and should not be used to fix
  317. remote `Unregistered redirect_uri` errors.
  318. This variable exists because the local OAuth flow starts a browser on the same
  319. machine as the MCP server and listens for the callback on a local HTTP server,
  320. for example `http://127.0.0.1:8888/callback`.
  321. Remote MCP OAuth is different. In `GITLAB_MCP_OAUTH=true` mode, the MCP client
  322. provides its own callback URL during `/authorize`. `GITLAB_OAUTH_REDIRECT_URI`
  323. does not replace that client-provided URL.
  324. | Mode | Enable with | Callback variable | GitLab redirect URI |
  325. | ---------------- | ----------------------- | ---------------------------------- | ------------------------------------------------------- |
  326. | Local OAuth | `GITLAB_USE_OAUTH=true` | `GITLAB_OAUTH_REDIRECT_URI` | `http://127.0.0.1:8888/callback` or your local callback |
  327. | Remote MCP OAuth | `GITLAB_MCP_OAUTH=true` | `GITLAB_OAUTH_CALLBACK_PROXY=true` | `{MCP_SERVER_URL}/callback` |
  328. Use `GITLAB_OAUTH_REDIRECT_URI` only when the MCP server itself owns the local
  329. browser callback. Use `GITLAB_OAUTH_CALLBACK_PROXY=true` when a remote MCP client
  330. owns the callback URL.
  331. **How it works**: You deploy this MCP server somewhere with a public HTTPS URL. MCP
  332. clients connect to `{MCP_SERVER_URL}/mcp`. The server handles the OAuth 2.0 flow,
  333. exchanging credentials with GitLab on behalf of the client.
  334. **Prerequisites**:
  335. 1. A publicly accessible HTTPS server URL (`MCP_SERVER_URL`) — use [ngrok](https://ngrok.com) for local testing
  336. 2. A pre-registered GitLab OAuth application with `api` (or `read_api`) scopes
  337. — Go to `Admin area` → `Applications`, set Redirect URI to `{MCP_SERVER_URL}/callback`
  338. | Environment Variable | Required | Description |
  339. | ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
  340. | `GITLAB_MCP_OAUTH` | ✅ | Set to `true` to enable |
  341. | `GITLAB_API_URL` | ✅ | GitLab API base URL. Do not embed credentials (`user:pass@`) in the URL; they are ignored. A comma in a password must be written as `%2C`. |
  342. | `GITLAB_OAUTH_APP_ID` | ✅ | GitLab OAuth Application ID |
  343. | `MCP_SERVER_URL` | ✅ | Public HTTPS URL of this MCP server |
  344. | `STREAMABLE_HTTP` | ✅ | Must be `true` |
  345. | `GITLAB_OAUTH_CALLBACK_PROXY` | optional | Set to `true` to use the MCP server's fixed `/callback` URL |
  346. | `GITLAB_OAUTH_ALLOWED_REDIRECT_URIS` | optional | Client callback URLs that callback proxy mode will redirect to (default: Claude, ChatGPT, Cursor and loopback callbacks; `defaults,<url>` to add one) |
  347. | `GITLAB_OAUTH_SCOPES` | optional | Comma-separated scopes (default: `api,read_api,read_user`) |
  348. | `GITLAB_OAUTH_ALLOWED_GROUPS` | optional | Comma-separated group full paths — only members (and subgroup members) may use the server (replaces deprecated `GITLAB_ALLOWED_GROUPS`) |
  349. | `OAUTH_DISABLE_REFRESH_TOKEN` | optional | Set to `true` to issue no refresh tokens: users re-authorize in the browser each time the GitLab access token expires (2 h), regardless of the session TTL |
  350. When `STREAMABLE_HTTP=true`, server-side GitLab credentials (`GITLAB_PERSONAL_ACCESS_TOKEN`, `GITLAB_JOB_TOKEN`, `GITLAB_AUTH_COOKIE_PATH`, or `GITLAB_USE_OAUTH`) require `REMOTE_AUTHORIZATION=true`, `GITLAB_MCP_OAUTH=true`, or `STREAMABLE_HTTP_AUTH_TOKEN`.
  351. > **Troubleshooting `Unregistered redirect_uri`**
  352. >
  353. > Check the `redirect_uri` in the browser URL. If it points to a client callback
  354. > such as `http://127.0.0.1:xxxxx/.../callback`, enable:
  355. >
  356. > ```env
  357. > GITLAB_OAUTH_CALLBACK_PROXY=true
  358. > ```
  359. >
  360. > Do not fix remote MCP OAuth by changing `GITLAB_OAUTH_REDIRECT_URI`. That
  361. > variable is for local OAuth (`GITLAB_USE_OAUTH`) only.
  362. ```shell
  363. docker run -i --rm \
  364. -e HOST=0.0.0.0 \
  365. -e GITLAB_MCP_OAUTH=true \
  366. -e GITLAB_OAUTH_CALLBACK_PROXY=true \
  367. -e STREAMABLE_HTTP=true \
  368. -e MCP_SERVER_URL=https://your-server.example.com \
  369. -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  370. -e GITLAB_OAUTH_APP_ID=your_app_id \
  371. -p 3000:3002 \
  372. zereight050/gitlab-mcp
  373. ```
  374. MCP client configuration:
  375. ```json
  376. {
  377. "mcpServers": {
  378. "gitlab": {
  379. "type": "http",
  380. "url": "https://your-server.example.com/mcp"
  381. }
  382. }
  383. }
  384. ```
  385. #### Using Remote Authorization (`REMOTE_AUTHORIZATION`)
  386. > **For server/remote deployments only.** Each HTTP caller provides their own GitLab token directly in request headers — no OAuth flow involved.
  387. For multi-user or multi-tenant deployments where each caller provides their own
  388. GitLab token in the HTTP request header. No OAuth flow — the MCP server forwards
  389. the token to GitLab on behalf of the caller.
  390. **Header priority**: `Private-Token` > `JOB-TOKEN` > `Authorization: Bearer`
  391. | Environment Variable | Required | Description |
  392. | --------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
  393. | `REMOTE_AUTHORIZATION` | ✅ | Set to `true` to enable |
  394. | `STREAMABLE_HTTP` | ✅ | Must be `true` |
  395. | `ENABLE_DYNAMIC_API_URL` | optional | Allow per-request GitLab URL via `X-GitLab-API-URL` header |
  396. | `GITLAB_ALLOWED_HOSTS` | optional | Comma-separated allowed `X-GitLab-API-URL` hosts; `GITLAB_API_URL` hosts are always allowed. Also trusted as download redirect targets (release assets, job artifacts, uploaded attachments); list private-network hosts here |
  397. | `GITLAB_ALLOW_UNAUTHENTICATED_TOOL_DISCOVERY` | optional | Allow unauthenticated `initialize`, `notifications/initialized`, `tools/list`, and `server/discover` only (tool calls still require auth) |
  398. | `MCP_SERVER_URL` / `MCP_ALLOWED_HOSTS` / `MCP_ALLOWED_ORIGINS` | optional | Allowed public `/mcp` host/origin values for DNS rebinding protection |
  399. | `MCP_TRUST_PROXY` | optional | Trust `Forwarded` / `X-Forwarded-*` headers behind a reverse proxy (download URLs, Express `req.ip`, `/mcp` IP rate limits, OAuth rate limits) |
  400. `GITLAB_ALLOW_UNAUTHENTICATED_TOOL_DISCOVERY=true` is intended for MCP gateways
  401. or admin UIs that need to inspect tool metadata before a user provides a GitLab
  402. token. Leave it disabled unless the tool list is safe to expose in your deployment.
  403. When `MCP_SERVER_URL` is not set, remote download URLs fall back to the local
  404. server address. Set `MCP_TRUST_PROXY=true` only if the server is reachable through a
  405. trusted reverse proxy and direct client access to the MCP server is blocked.
  406. This enables Express `trust proxy` for Streamable HTTP and SSE, derives public
  407. download URLs from `Forwarded` / `X-Forwarded-Proto` / `X-Forwarded-Host` /
  408. `X-Forwarded-Prefix`, and keeps OAuth endpoint rate limiting working when
  409. proxies send `X-Forwarded-For` with a client port (for example `1.2.3.4:5678`).
  410. Existing OAuth+proxy deployments must set this explicitly after the flag was
  411. introduced.
  412. **Example request headers**:
  413. ```http
  414. Private-Token: glpat-xxxxxxxxxxxxxxxxxxxx
  415. ```
  416. or using a Bearer token:
  417. ```http
  418. Authorization: Bearer glpat-xxxxxxxxxxxxxxxxxxxx
  419. ```
  420. > ⚠️ `REMOTE_AUTHORIZATION` is **not compatible** with SSE transport. `STREAMABLE_HTTP=true` is required.
  421. ### Environment Variables
  422. Use the dedicated reference for the full environment variable list:
  423. - [Environment Variables Reference](./docs/configuration/environment-variables.md)
  424. Most users only need one of these starting sets:
  425. - **Local PAT**: `GITLAB_PERSONAL_ACCESS_TOKEN`, `GITLAB_API_URL`
  426. - **Local OAuth**: `GITLAB_USE_OAUTH=true`, `GITLAB_OAUTH_CLIENT_ID`, `GITLAB_OAUTH_REDIRECT_URI`, `GITLAB_API_URL`
  427. - **Remote multi-user HTTP**: `STREAMABLE_HTTP=true`, `REMOTE_AUTHORIZATION=true` (or `GITLAB_MCP_OAUTH=true`), `MCP_TRUST_PROXY=true` (behind a reverse proxy), `MAX_REQUESTS_PER_MINUTE=300`, `MCP_SERVER_URL` or `MCP_ALLOWED_HOSTS`, `HOST`, `PORT`
  428. - **Multiple side-by-side deployments**: set a distinct `MCP_SERVER_NAME` per instance (e.g. `gitlab-selfhosted-readonly`) so clients, logs, and telemetry can tell them apart
  429. - **Multi-pod HPA (stateless)**: above + `OAUTH_STATELESS_MODE=true`, `OAUTH_STATELESS_SECRET` (same across all pods). See [Stateless Mode](./docs/configuration/stateless-mode.md).
  430. Commonly referenced variables:
  431. - `GITLAB_API_URL`
  432. - `GITLAB_PERSONAL_ACCESS_TOKEN`
  433. - `GITLAB_USE_OAUTH`
  434. - `REMOTE_AUTHORIZATION`
  435. - `MCP_TRUST_PROXY`
  436. - `MAX_REQUESTS_PER_MINUTE`
  437. - `MAX_SESSIONS`
  438. - `MCP_ALLOWED_HOSTS`
  439. - `MCP_ALLOWED_ORIGINS`
  440. - `GITLAB_MCP_OAUTH`
  441. - `GITLAB_OAUTH_CALLBACK_PROXY`
  442. - `GITLAB_OAUTH_ALLOWED_REDIRECT_URIS`
  443. - `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR`
  444. - `OAUTH_DISABLE_REFRESH_TOKEN`
  445. - `OAUTH_STATELESS_MODE`
  446. - `OAUTH_STATELESS_SECRET`
  447. The reference document also covers:
  448. - auth and OAuth variables
  449. - MCP OAuth proxy variables
  450. - project and tool filtering variables
  451. - dynamic tool discovery via `discover_tools` (on-demand toolset activation)
  452. - transport and session variables
  453. - proxy and TLS variables
  454. - opt-in SIEM audit log (`GITLAB_AUDIT_LOG`)
  455. For callback proxy mode details, see [GitLab MCP OAuth Callback Proxy](./docs/auth/oauth-callback-proxy.md).
  456. #### SSE session limits
  457. `GET /sse` is subject to the same remote-transport controls as Streamable HTTP:
  458. - **Capacity:** at most `MAX_SESSIONS` concurrent SSE sessions (default 1000); further connections get `503`.
  459. - **Creation rate limit:** new connections are limited to `MAX_REQUESTS_PER_MINUTE` per client IP (default 60); excess connections get `429`.
  460. - **Idle timeout:** a session that receives no `POST /messages` request for `SESSION_TIMEOUT_SECONDS` (default 1 hour) is closed, so an idle client must reconnect instead of holding a capacity slot. Unlike Streamable HTTP, holding the SSE stream open does **not** count as activity.
  461. - `/health` returns `503` with `status: "degraded"` while the instance is at capacity.
  462. Tune these with [`MAX_SESSIONS`](./docs/configuration/environment-variables.md#max_sessions), `MAX_REQUESTS_PER_MINUTE`, and `SESSION_TIMEOUT_SECONDS`.
  463. #### Streamable HTTP session timeout
  464. Streamable HTTP sessions use the same `SESSION_TIMEOUT_SECONDS` idle timeout in every mode, including a server-side token without `REMOTE_AUTHORIZATION` or `GITLAB_MCP_OAUTH`: a session with no `POST /mcp` request for that long is closed, and its next request gets `404` so the client re-initializes. An open `GET /mcp` stream pauses the timer until the stream closes or the next `POST /mcp` arrives, so a client with a stream open still expires `SESSION_TIMEOUT_SECONDS` after its last `POST`.
  465. ### Remote Authorization Setup (Multi-User Support)
  466. When using `REMOTE_AUTHORIZATION=true`, the MCP server can support multiple users, each with their own GitLab token passed via HTTP headers. This is useful for:
  467. - Shared MCP server instances where each user needs their own GitLab access
  468. - IDE integrations that can inject user-specific tokens into MCP requests
  469. **Setup Example:**
  470. ```bash
  471. # Start server with remote authorization
  472. docker run -d \
  473. -e HOST=0.0.0.0 \
  474. -e STREAMABLE_HTTP=true \
  475. -e REMOTE_AUTHORIZATION=true \
  476. -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  477. -e GITLAB_PERMISSION_MODE=readonly \
  478. -e SESSION_TIMEOUT_SECONDS=3600 \
  479. -p 3333:3002 \
  480. zereight050/gitlab-mcp
  481. ```
  482. **Client Configuration:**
  483. Your IDE or MCP client must send one of these headers with each request:
  484. ```
  485. Authorization: Bearer glpat-xxxxxxxxxxxxxxxxxxxx
  486. ```
  487. or
  488. ```
  489. Private-Token: glpat-xxxxxxxxxxxxxxxxxxxx
  490. ```
  491. The token is stored per session (identified by `mcp-session-id` header) and reused for subsequent requests in the same session. The session belongs to the GitLab user of that token: a request with another user's token gets `404 Session not found`, and `GET` / `DELETE /mcp` without a token get `401`.
  492. #### Remote Authorization Client Configuration Example with Cursor
  493. ```json
  494. {
  495. "mcpServers": {
  496. "GitLab": {
  497. "url": "http(s)://<your_mcp_gitlab_server>/mcp",
  498. "headers": {
  499. "Authorization": "Bearer glpat-..."
  500. }
  501. }
  502. }
  503. }
  504. ```
  505. **Important Notes:**
  506. - Remote authorization **only works with Streamable HTTP transport**
  507. - Each session is isolated - tokens from one session cannot access another session's data
  508. Tokens are automatically cleaned up when sessions close
  509. - **Session timeout:** Auth tokens expire after `SESSION_TIMEOUT_SECONDS` (default 1 hour) of inactivity. After timeout the session is closed and its next request gets `404`, so the client re-initializes with its auth headers.
  510. - Each request resets the timeout timer for that session
  511. - **Rate limiting:** `/mcp` requests are limited to `MAX_REQUESTS_PER_MINUTE` per client IP, and per MCP session when using OAuth or remote authorization (default 60). The per-IP limit uses a fixed 60-second window, counts per server process, and also covers `GET /mcp`; stateless mode skips the per-session limit. See [environment-variables.md](docs/configuration/environment-variables.md#max_requests_per_minute).
  512. - **Capacity limit:** Server accepts up to `MAX_SESSIONS` concurrent sessions (default 1000)
  513. ### MCP OAuth Setup (Claude.ai Native OAuth)
  514. When using `GITLAB_MCP_OAUTH=true`, the server acts as an OAuth proxy to your GitLab
  515. instance. Claude.ai (and any MCP-spec-compliant client) handles the entire browser
  516. authentication flow automatically — no manual Personal Access Token management needed.
  517. **Prerequisites:**
  518. A **pre-registered GitLab OAuth application** is required. GitLab restricts dynamically
  519. registered (unverified) applications to the `mcp` scope, which is insufficient for API
  520. calls (need `api` or `read_api`).
  521. 1. Go to your GitLab instance → **Admin Area > Applications** (instance-wide) or **User Settings > Applications** (personal)
  522. 2. Create a new application with:
  523. - **Confidential**: unchecked
  524. - **Scopes**: `api`, `read_api`, `read_user` (or whichever scopes you intend to request via `GITLAB_OAUTH_SCOPES`)
  525. 3. Save and copy the **Application ID** — this is your `GITLAB_OAUTH_APP_ID`
  526. **How it works:**
  527. 1. User adds your MCP server URL in Claude.ai
  528. 2. Claude.ai discovers OAuth endpoints via `/.well-known/oauth-authorization-server`
  529. 3. Claude.ai registers itself via Dynamic Client Registration (`POST /register`) — handled locally by the MCP server (each client gets a virtual client ID)
  530. 4. Claude.ai redirects the user's browser to GitLab's login page using the pre-registered OAuth application
  531. 5. User authenticates; GitLab redirects back to `https://claude.ai/api/mcp/auth_callback`
  532. 6. Claude.ai sends `Authorization: Bearer <token>` on every MCP request
  533. 7. Server validates the token with GitLab and stores it per session
  534. **Server setup:**
  535. ```bash
  536. docker run -d \
  537. -e STREAMABLE_HTTP=true \
  538. -e GITLAB_MCP_OAUTH=true \
  539. -e GITLAB_OAUTH_APP_ID="your-gitlab-oauth-app-client-id" \
  540. -e GITLAB_API_URL="https://gitlab.example.com/api/v4" \
  541. -e MCP_SERVER_URL="https://your-mcp-server.example.com" \
  542. -p 3002:3002 \
  543. zereight050/gitlab-mcp
  544. ```
  545. For local development (HTTP allowed):
  546. ```bash
  547. MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL=true \
  548. STREAMABLE_HTTP=true \
  549. GITLAB_MCP_OAUTH=true \
  550. GITLAB_OAUTH_APP_ID=your-gitlab-oauth-app-client-id \
  551. MCP_SERVER_URL=http://localhost:3002 \
  552. GITLAB_API_URL=https://gitlab.com/api/v4 \
  553. node build/index.js
  554. ```
  555. **Claude.ai configuration:**
  556. ```json
  557. {
  558. "mcpServers": {
  559. "GitLab": {
  560. "url": "https://your-mcp-server.example.com/mcp"
  561. }
  562. }
  563. }
  564. ```
  565. No `headers` field is needed — Claude.ai obtains the token via OAuth automatically.
  566. **Environment variables:**
  567. | Variable | Required | Description |
  568. | ------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  569. | `GITLAB_MCP_OAUTH` | Yes | Set to `true` to enable |
  570. | `GITLAB_OAUTH_APP_ID` | Yes | Client ID of the pre-registered GitLab OAuth application |
  571. | `MCP_SERVER_URL` | Yes | Public HTTPS URL of your MCP server; also allowed for `/mcp` Host/Origin checks |
  572. | `GITLAB_API_URL` | Yes | Your GitLab instance API URL (e.g. `https://gitlab.com/api/v4`). Do not embed credentials (`user:pass@`) in the URL; they are ignored. A comma in a password must be written as `%2C`. |
  573. | `STREAMABLE_HTTP` | Yes | Must be `true` (SSE is not supported) |
  574. | `GITLAB_OAUTH_SCOPES` | No | Comma-separated GitLab scopes to request (e.g. `api,read_user`). Defaults to `api` (or `read_api` when the effective permission mode is `readonly`). The pre-registered application must be configured with at least these scopes. |
  575. | `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR` | No | Per-IP limit (fixed 1-hour window) for Dynamic Client Registration (`POST /register`). Default `20`/hour; range `1`–`1000`. Raise when clients (e.g. multiple IDE windows) hit registration throttling. Not a GitLab API limit. |
  576. | `OAUTH_DISABLE_REFRESH_TOKEN` | No | Set `true` to drop `refresh_token` from `/token` responses and reject the refresh grant with `invalid_grant`, so users re-authorize in the browser when the GitLab access token expires. Default `false`. In callback proxy mode, MCP clients that follow this server's flow never receive a GitLab refresh token (in passthrough the client can get one from GitLab directly). This is a re-authorization policy for standard MCP clients, not a security boundary. Refresh tokens issued before enabling stay valid until revoked in GitLab under **User Settings → Applications → Authorized applications → Revoke**. |
  577. | `MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL` | No | Set `true` for local HTTP dev only |
  578. **Important Notes:**
  579. - MCP OAuth **only works with Streamable HTTP transport** (`SSE=true` is incompatible)
  580. - Each user session stores its own OAuth token — sessions are fully isolated
  581. - Session timeout, rate limiting, and capacity limits apply identically to the
  582. `REMOTE_AUTHORIZATION` mode (`SESSION_TIMEOUT_SECONDS`, `MAX_REQUESTS_PER_MINUTE`,
  583. `MAX_SESSIONS`)
  584. - **DCR rate limiting:** `POST /register` is limited to `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR`
  585. per client IP (default 20/hour). Separate from `/mcp` limits and GitLab API quotas.
  586. See [environment-variables.md](docs/configuration/environment-variables.md#oauth_register_rate_limit_per_hour).
  587. - **Header auth fallback:** when `Private-Token` or `JOB-TOKEN` request headers are
  588. present, OAuth validation is skipped and the raw token is used directly for that
  589. session. This allows PATs and CI job tokens to be used alongside the OAuth flow on
  590. the same server instance. `Authorization: Bearer` is always treated as an OAuth
  591. token — use `Private-Token` for PAT-based header auth.
  592. ## Agent Skill Files
  593. Skill + CLI is an equal path to MCP (see [Skill + CLI](#skill--cli-no-mcp-required)). Pre-built skill files are available in [`skills/gitlab-mcp/`](./skills/gitlab-mcp/) for AI agents that support skill/instruction loading (Claude Code, GitHub Copilot, Cursor, etc.).
  594. - **[SKILL.md](./skills/gitlab-mcp/SKILL.md)** — Core guide (~800 tokens) with toolset overview, key workflows, and parameter hints
  595. - **[reference/](./skills/gitlab-mcp/reference/)** — Detailed workflow docs for code review, merge requests, issues, pipelines, and vulnerability triage
  596. Install with the `skills` CLI:
  597. ```bash
  598. npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill
  599. ```
  600. Register the skill directory in your AI client to get optimal tool usage guidance without relying solely on the full ListTools response.
  601. ## Tools 🛠️
  602. <details>
  603. <summary>Click to expand</summary>
  604. <!-- TOOLS-START -->
  605. 1. `merge_merge_request` - Merge a merge request
  606. 2. `approve_merge_request` - Approve a merge request
  607. 3. `unapprove_merge_request` - Unapprove a merge request
  608. 4. `get_merge_request_approval_state` - Get merge request approval details including approvers
  609. 5. `get_merge_request_conflicts` - Get the conflicts of a merge request
  610. 6. `list_merge_request_pipelines` - List pipelines for a merge request with pagination
  611. 7. `execute_graphql` - Execute a GitLab GraphQL query
  612. 8. `create_or_update_file` - Create or update a file in a GitLab project
  613. 9. `search_repositories` - Search for GitLab projects
  614. 10. `create_repository` - Create a new GitLab project
  615. 11. `create_group` - Create new group or subgroup
  616. 12. `get_file_contents` - Get the contents of one file from a GitLab project
  617. 13. `push_files` - Push multiple files in a single commit
  618. 14. `create_issue` - Create a new issue
  619. 15. `create_merge_request` - Create a new merge request
  620. 16. `fork_repository` - Fork a project to your account or specified namespace
  621. 17. `create_branch` - Create a new branch
  622. 18. `get_branch` - Get branch details (commit, protection status)
  623. 19. `list_branches` - List branches in project with search filter
  624. 20. `delete_branch` - Delete branch from project
  625. 21. `list_protected_branches` - List protected branches in a project, supports search filter
  626. 22. `get_protected_branch` - Get details of a single protected branch (access levels, force push settings)
  627. 23. `protect_branch` - Protect a repository branch (set push/merge/unprotect access levels)
  628. 24. `update_protected_branch` - Update an existing protected branch rule in place (access levels, force push, code owner approval)
  629. 25. `unprotect_branch` - Remove protection from a previously protected branch
  630. 26. `update_default_branch` - Change the default branch of a project
  631. 27. `get_merge_request` - Get details of a merge request (merge_request_iid or source_branch required). Set include_summaries=true for deployment/commit/approval summaries
  632. 28. `get_merge_request_diffs` - Get the changes/diffs of a merge request (merge_request_iid or source_branch required)
  633. 29. `list_merge_request_changed_files` - List changed file paths in a merge request without diff content (merge_request_iid or source_branch required)
  634. 30. `list_merge_request_diffs` - List merge request diffs with pagination (merge_request_iid or source_branch required)
  635. 31. `get_merge_request_file_diff` - Get diffs for specific files from a merge request (merge_request_iid or source_branch required)
  636. 32. `list_merge_request_versions` - List all versions of a merge request
  637. 33. `get_merge_request_version` - Get a specific version of a merge request
  638. 34. `get_branch_diffs` - Get diffs between two branches or commits
  639. 35. `update_merge_request` - Update a merge request (merge_request_iid or source_branch required)
  640. 36. `create_note` - Create a new note (comment) to an issue or merge request
  641. 37. `create_merge_request_thread` - Create a new thread on a merge request
  642. 38. `resolve_merge_request_thread` - Resolve a thread on a merge request
  643. 39. `mr_discussions` - List discussion items for a merge request
  644. 40. `get_merge_request_discussion` - Get a single discussion item for a merge request
  645. 41. `delete_merge_request_discussion_note` - Delete a discussion note on a merge request
  646. 42. `update_merge_request_discussion_note` - Update a discussion note on a merge request
  647. 43. `create_merge_request_discussion_note` - Add a new discussion note to an existing merge request thread
  648. 44. `create_merge_request_note` - Add a new note to a merge request
  649. 45. `delete_merge_request_note` - Delete an existing merge request note
  650. 46. `get_merge_request_note` - Get a specific note for a merge request
  651. 47. `get_merge_request_notes` - List notes for a merge request
  652. 48. `update_merge_request_note` - Modify an existing merge request note
  653. 49. `get_draft_note` - Get a single draft note from a merge request
  654. 50. `list_draft_notes` - List draft notes for a merge request
  655. 51. `create_draft_note` - Create a draft note for a merge request
  656. 52. `update_draft_note` - Update an existing draft note
  657. 53. `delete_draft_note` - Delete a draft note
  658. 54. `publish_draft_note` - Publish a single draft note
  659. 55. `bulk_publish_draft_notes` - Publish all draft notes for a merge request. Optionally sets reviewer_state and posts a summary note (GitLab 19.2+). Can set reviewer_state even with no drafts.
  660. 56. `list_merge_request_emoji_reactions` - List all emoji reactions on a merge request
  661. 57. `list_merge_request_note_emoji_reactions` - List all emoji reactions on a merge request note. Pass discussion_id for discussion thread replies.
  662. 58. `create_merge_request_emoji_reaction` - Add an emoji reaction to a merge request (e.g. thumbsup, rocket, eyes)
  663. 59. `delete_merge_request_emoji_reaction` - Remove an emoji reaction from a merge request
  664. 60. `create_merge_request_note_emoji_reaction` - Add an emoji reaction to a merge request note. Pass discussion_id for discussion thread replies.
  665. 61. `delete_merge_request_note_emoji_reaction` - Remove an emoji reaction from a merge request note. Pass discussion_id for discussion thread replies.
  666. 62. `update_issue_note` - Modify an existing issue thread note
  667. 63. `create_issue_note` - Add a note to an issue, optionally replying to a discussion thread
  668. 64. `list_issue_emoji_reactions` - List all emoji reactions on an issue
  669. 65. `list_issue_note_emoji_reactions` - List all emoji reactions on an issue note. Pass discussion_id for discussion thread replies.
  670. 66. `create_issue_emoji_reaction` - Add an emoji reaction to an issue (e.g. thumbsup, rocket, eyes)
  671. 67. `delete_issue_emoji_reaction` - Remove an emoji reaction from an issue
  672. 68. `create_issue_note_emoji_reaction` - Add an emoji reaction to an issue note. Pass discussion_id for discussion thread replies.
  673. 69. `delete_issue_note_emoji_reaction` - Remove an emoji reaction from an issue note. Pass discussion_id for discussion thread replies.
  674. 70. `list_issues` - List issues (default: created by current user; use scope='all' for all)
  675. 71. `my_issues` - List issues assigned to the authenticated user
  676. 72. `get_issue` - Get one issue. Slim nested milestone by default; full_response=true for the complete milestone
  677. 73. `update_issue` - Update an issue. Slim confirmation by default; full_response=true for the complete object
  678. 74. `update_issue_description_patch` - Patch an issue description (search/replace or unified diff) without resending the full body. dry_run previews; create_note summarizes
  679. 75. `reorder_issue` - Move an issue within the manual sort order shown on issue boards. move_after_id and move_before_id take the neighbor issue's global id (the `id` field), not its iid; pass at least one. Returns the reordered issue.
  680. 76. `delete_issue` - Delete an issue
  681. 77. `list_todos` - List GitLab to-do items for the current user
  682. 78. `mark_todo_done` - Mark a GitLab to-do item as done
  683. 79. `mark_all_todos_done` - Mark all pending GitLab to-do items as done for the current user
  684. 80. `list_issue_links` - List all issue links for a specific issue
  685. 81. `list_issue_discussions` - List discussions for an issue
  686. 82. `list_issue_label_events` - List an issue's label history: who added or removed which label, when. Lean events: created_at, user.username, action, label.name (label is null if deleted). Paginated via page/per_page.
  687. 83. `list_issue_state_events` - List an issue's state history: who closed or reopened it, when. Lean events: created_at, user.username, state. Paginated via page/per_page.
  688. 84. `get_issue_link` - Get a specific issue link
  689. 85. `create_issue_link` - Create an issue link between two issues
  690. 86. `delete_issue_link` - Delete an issue link
  691. 87. `list_namespaces` - List all namespaces (users and groups) available to the current user. Filter by kind='group' for groups only.
  692. 88. `get_namespace` - Get details of a namespace (user or group) by ID or path. Groups are namespaces with kind='group'.
  693. 89. `verify_namespace` - Verify if a namespace path exists. Use parent_id to scope the check to a specific parent namespace — required for nested namespaces where the same path may exist under different parents.
  694. 90. `get_project` - Get details of a specific project
  695. 91. `list_projects` - List projects accessible by the current user
  696. 92. `update_project` - Update project settings such as description, visibility, default branch, and feature access levels
  697. 93. `list_project_members` - List members of a GitLab project
  698. 94. `list_group_members` - List members of a GitLab group with optional name or username search
  699. 95. `list_labels` - List labels for a project
  700. 96. `get_label` - Get a single label from a project
  701. 97. `create_label` - Create a new label in a project
  702. 98. `update_label` - Update an existing label in a project
  703. 99. `delete_label` - Delete a label from a project
  704. 100. `list_group_projects` - List projects in a group
  705. 101. `list_wiki_pages` - List wiki pages in a project
  706. 102. `get_wiki_page` - Get details of a specific wiki page
  707. 103. `create_wiki_page` - Create a wiki page in a project
  708. 104. `update_wiki_page` - Update a wiki page in a project
  709. 105. `delete_wiki_page` - Delete a wiki page from a project
  710. 106. `list_group_wiki_pages` - List wiki pages in a group
  711. 107. `get_group_wiki_page` - Get details of a specific group wiki page
  712. 108. `create_group_wiki_page` - Create a wiki page in a group
  713. 109. `update_group_wiki_page` - Update a wiki page in a group
  714. 110. `delete_group_wiki_page` - Delete a wiki page from a group
  715. 111. `get_repository_tree` - List files and directories in a repository
  716. 112. `list_pipelines` - List pipelines with filtering options
  717. 113. `get_pipeline` - Get details of a specific pipeline
  718. 114. `get_pipeline_variables` - Get variables configured for a pipeline
  719. 115. `get_pipeline_test_report` - Get pipeline test report
  720. 116. `get_pipeline_test_report_summary` - Get pipeline test report summary
  721. 117. `delete_pipeline` - Delete a pipeline. Requires the project Owner role, cannot be undone, and does not automatically delete child pipelines.
  722. 118. `update_pipeline_metadata` - Update pipeline metadata
  723. 119. `list_deployments` - List deployments with filtering options
  724. 120. `get_deployment` - Get deployment details, including approval_summary, approvals, and pending_approval_count when GitLab provides them
  725. 121. `create_deployment` - Create a deployment
  726. 122. `update_deployment` - Update a deployment status
  727. 123. `delete_deployment` - Delete a deployment
  728. 124. `list_deployment_merge_requests` - List merge requests shipped with a deployment
  729. 125. `approve_deployment` - Approve or reject a protected-environment deployment
  730. 126. `list_environments` - List environments in a project
  731. 127. `get_environment` - Get details of a specific environment
  732. 128. `update_environment` - Update an environment
  733. 129. `delete_environment` - Delete a stopped environment
  734. 130. `stop_environment` - Stop an environment
  735. 131. `stop_stale_environments` - Stop eligible stale environments; protected environments are excluded and environments are stopped, not deleted
  736. 132. `delete_review_app_environments` - Schedule deletion of stopped review-app environments one week later; dry_run defaults to true and actual scheduling requires dry_run=false
  737. 133. `list_pipeline_triggers` - List project pipeline trigger tokens
  738. 134. `get_pipeline_trigger` - Get a project pipeline trigger
  739. 135. `create_pipeline_trigger` - Create a project pipeline trigger
  740. 136. `update_pipeline_trigger` - Update a project pipeline trigger
  741. 137. `delete_pipeline_trigger` - Delete a project pipeline trigger
  742. 138. `trigger_pipeline` - Trigger a pipeline with a pipeline trigger token
  743. 139. `list_pipeline_jobs` - List all jobs in a specific pipeline
  744. 140. `list_pipeline_trigger_jobs` - List trigger jobs (bridges) in a pipeline
  745. 141. `get_pipeline_job` - Get details of a GitLab pipeline job number
  746. 142. `get_pipeline_job_output` - Get a pipeline job trace, with end-based pagination or full-log substring/regex search
  747. 143. `validate_ci_lint` - Validate provided GitLab CI/CD YAML content for a project
  748. 144. `validate_project_ci_lint` - Validate an existing .gitlab-ci.yml configuration for a project
  749. 145. `list_ci_catalog_resources` - List GitLab CI/CD Catalog resources/components visible to the user
  750. 146. `get_ci_catalog_resource` - Get details for a GitLab CI/CD Catalog resource, including versions and components
  751. 147. `create_pipeline` - Create a new pipeline for a branch or tag
  752. 148. `retry_pipeline` - Retry a failed or canceled pipeline
  753. 149. `cancel_pipeline` - Cancel a running pipeline
  754. 150. `list_pipeline_schedules` - List pipeline schedules in a project, optionally filtered to active or inactive
  755. 151. `get_pipeline_schedule` - Get details of a specific pipeline schedule, including its variables and last pipeline
  756. 152. `list_pipeline_schedule_pipelines` - List the pipelines that a pipeline schedule has triggered
  757. 153. `create_pipeline_schedule` - Create a new pipeline schedule for a branch or tag
  758. 154. `update_pipeline_schedule` - Update an existing pipeline schedule
  759. 155. `delete_pipeline_schedule` - Delete a pipeline schedule
  760. 156. `play_pipeline_schedule` - Run a pipeline schedule immediately
  761. 157. `take_ownership_pipeline_schedule` - Take ownership of a pipeline schedule
  762. 158. `get_pipeline_schedule_variable` - Get a single variable of a pipeline schedule
  763. 159. `create_pipeline_schedule_variable` - Create a variable for a pipeline schedule
  764. 160. `update_pipeline_schedule_variable` - Update a variable of a pipeline schedule
  765. 161. `delete_pipeline_schedule_variable` - Delete a variable from a pipeline schedule
  766. 162. `play_pipeline_job` - Run a manual pipeline job
  767. 163. `play_pipeline_jobs` - Play multiple manual pipeline jobs sequentially
  768. 164. `retry_pipeline_job` - Retry a failed or canceled pipeline job
  769. 165. `cancel_pipeline_job` - Cancel a running pipeline job
  770. 166. `erase_pipeline_job` - Erase a pipeline job log and artifacts
  771. 167. `wait_for_pipeline` - Wait for a pipeline to reach a terminal status
  772. 168. `wait_for_job` - Wait for a job to reach a terminal status
  773. 169. `list_job_artifacts` - List artifact files in a job's archive
  774. 170. `download_job_artifacts` - Download job artifact archive (zip) and save it under the download directory
  775. 171. `get_job_artifact_file` - Get content of a single file from a job's artifacts
  776. 172. `list_merge_requests` - List merge requests (without project_id: user's MRs; with project_id: project MRs)
  777. 173. `list_group_merge_requests` - List merge requests across all projects of a group and its subgroups
  778. 174. `list_milestones` - List milestones with filtering options
  779. 175. `get_milestone` - Get details of a specific milestone
  780. 176. `create_milestone` - Create a new milestone
  781. 177. `edit_milestone` - Edit an existing milestone
  782. 178. `delete_milestone` - Delete a milestone
  783. 179. `get_milestone_issue` - Get issues associated with a specific milestone
  784. 180. `get_milestone_merge_requests` - Get merge requests associated with a specific milestone
  785. 181. `promote_milestone` - Promote a milestone to the next stage
  786. 182. `get_milestone_burndown_events` - Get burndown events for a specific milestone
  787. 183. `list_group_milestones` - List group milestones with filtering options
  788. 184. `get_group_milestone` - Get details of a specific group milestone
  789. 185. `create_group_milestone` - Create a new group milestone
  790. 186. `edit_group_milestone` - Edit an existing group milestone
  791. 187. `delete_group_milestone` - Delete a group milestone
  792. 188. `get_group_milestone_issue` - Get issues associated with a specific group milestone
  793. 189. `get_group_milestone_merge_requests` - Get merge requests associated with a specific group milestone
  794. 190. `get_group_milestone_burndown_events` - Get burndown events for a specific group milestone
  795. 191. `get_users` - Get GitLab user details by usernames
  796. 192. `get_user` - Get user details by ID
  797. 193. `whoami` - Get current authenticated user details
  798. 194. `list_commits` - List repository commits with filtering options
  799. 195. `get_commit` - Get details of a specific commit
  800. 196. `get_commit_diff` - Get changes/diffs of a specific commit
  801. 197. `get_file_blame` - Get git blame for a file at a given ref. Each entry maps a contiguous range of source lines to the commit that last changed them (id, author, authored_date, message). Use range_start/range_end to limit blame to specific lines.
  802. 198. `list_commit_statuses` - List statuses for a commit
  803. 199. `create_commit_status` - Create or update the status of a commit
  804. 200. `list_group_iterations` - List group iterations with filtering options
  805. 201. `get_group_iteration` - Get a group iteration by ID, IID, or GraphQL GID
  806. 202. `update_group_iteration` - Update a manual group iteration's title, description, or dates
  807. 203. `create_group_iteration` - Create a group iteration, optionally in a given iteration cadence
  808. 204. `delete_group_iteration` - Delete a group iteration by ID, IID, or GraphQL GID
  809. 205. `list_project_iterations` - List the iterations available to a project with filtering options
  810. 206. `list_group_iteration_cadences` - List a group's iteration cadences with filtering options
  811. 207. `create_group_iteration_cadence` - Create an iteration cadence in a group
  812. 208. `update_group_iteration_cadence` - Update an iteration cadence's title, description, schedule, or automation
  813. 209. `delete_group_iteration_cadence` - Delete an iteration cadence
  814. 210. `upload_markdown` - Upload a file for use in markdown content
  815. 211. `download_attachment` - Download an uploaded file from a project (images returned as base64; other files, or images with local_path, are saved as new files under the download directory)
  816. 212. `health_check` - Check auth and versions. Always includes mcp_server_version. When authenticated, also GitLab version, revision, and enterprise from GET /api/v4/version. Version lookup failures omit those fields instead of failing
  817. 213. `list_events` - List events for the authenticated user (before/after: YYYY-MM-DD)
  818. 214. `get_project_events` - List events for a project (before/after: YYYY-MM-DD)
  819. 215. `list_releases` - List all releases for a project
  820. 216. `get_release` - Get a release by tag name
  821. 217. `create_release` - Create a new release
  822. 218. `update_release` - Update an existing release
  823. 219. `delete_release` - Delete a release (does not delete the tag)
  824. 220. `create_release_evidence` - Create release evidence (Premium/Ultimate)
  825. 221. `download_release_asset` - Download a release asset file by direct asset path
  826. 222. `list_tags` - List repository tags for a project
  827. 223. `get_tag` - Get a repository tag by name
  828. 224. `create_tag` - Create a new repository tag
  829. 225. `delete_tag` - Delete a repository tag
  830. 226. `get_tag_signature` - Get the X.509 signature of a signed tag (404 if unsigned)
  831. 227. `list_protected_tags` - List protected tags in a project
  832. 228. `get_protected_tag` - Get details of a single protected tag or wildcard (create access levels)
  833. 229. `protect_tag` - Protect a repository tag or wildcard (set who can create it)
  834. 230. `unprotect_tag` - Remove protection from a previously protected tag or wildcard
  835. 231. `get_work_item` - Get a work item with full details including status, hierarchy, type, and widgets
  836. 232. `list_work_items` - List work items with filters (type, state, search, assignees, labels)
  837. 233. `create_work_item` - Create a work item (issue, task, incident, epic, etc.) with full field support
  838. 234. `update_work_item` - Update a work item (title, description, labels, assignees, state, parent, custom fields, etc.)
  839. 235. `convert_work_item_type` - Convert a work item to a different type
  840. 236. `list_work_item_statuses` - List available statuses for a work item type (Premium/Ultimate)
  841. 237. `list_custom_field_definitions` - List custom field definitions for a work item type
  842. 238. `move_work_item` - Move a work item to a different project
  843. 239. `list_work_item_notes` - List notes and discussions on a work item
  844. 240. `create_work_item_note` - Add a note to a work item (supports Markdown, internal notes, threads)
  845. 241. `list_work_item_emoji_reactions` - List all emoji reactions on a work item
  846. 242. `list_work_item_note_emoji_reactions` - List all emoji reactions on a work item note (comment, thread, or thread reply)
  847. 243. `create_work_item_emoji_reaction` - Add an emoji reaction to a work item (e.g. thumbsup, rocket, eyes)
  848. 244. `delete_work_item_emoji_reaction` - Remove an emoji reaction from a work item
  849. 245. `create_work_item_note_emoji_reaction` - Add an emoji reaction to a work item note (comment, thread, or thread reply)
  850. 246. `delete_work_item_note_emoji_reaction` - Remove an emoji reaction from a work item note (comment, thread, or thread reply)
  851. 247. `get_timeline_events` - List timeline events for an incident
  852. 248. `create_timeline_event` - Create a timeline event on an incident
  853. 249. `list_webhooks` - List webhooks for a project or group
  854. 250. `create_webhook` - Create a webhook on a project or group
  855. 251. `update_webhook` - Update an existing project or group webhook
  856. 252. `delete_webhook` - Delete a project or group webhook
  857. 253. `list_webhook_events` - List recent webhook events (past 7 days)
  858. 254. `get_webhook_event` - Get full details of a specific webhook event
  859. 255. `search_code` - Search for code across all projects (requires advanced search or Zoekt)
  860. 256. `search_project_code` - Search for code within a specific project (requires advanced search or Zoekt)
  861. 257. `search_group_code` - Search for code within a specific group (requires advanced search or Zoekt)
  862. 258. `list_project_variables` - List CI/CD variables for a project
  863. 259. `get_project_variable` - Get a single CI/CD variable from a project
  864. 260. `create_project_variable` - Create a CI/CD variable for a project
  865. 261. `update_project_variable` - Update an existing CI/CD variable in a project
  866. 262. `delete_project_variable` - Delete a CI/CD variable from a project
  867. 263. `list_group_variables` - List CI/CD variables for a group
  868. 264. `get_group_variable` - Get a single CI/CD variable from a group
  869. 265. `create_group_variable` - Create a CI/CD variable for a group
  870. 266. `update_group_variable` - Update an existing CI/CD variable in a group
  871. 267. `delete_group_variable` - Delete a CI/CD variable from a group
  872. 268. `get_dependency_proxy_settings` - Get dependency proxy settings for a group
  873. 269. `update_dependency_proxy_settings` - Update dependency proxy settings for a group (enable/disable, credentials for authenticated Docker Hub pulls)
  874. 270. `list_dependency_proxy_blobs` - List cached dependency proxy blobs for a group
  875. 271. `purge_dependency_proxy_cache` - Schedule purge of all cached dependency proxy blobs for a group
  876. 272. `list_project_vulnerabilities` - List vulnerabilities for a project with optional state, severity, and report type filters (GraphQL-backed, cursor pagination)
  877. 273. `get_vulnerability` - Get full details of a specific vulnerability
  878. 274. `dismiss_vulnerability` - Dismiss a vulnerability with a reason (acceptable_risk, false_positive, used_in_tests, mitigating_control, not_applicable) and optional comment
  879. 275. `confirm_vulnerability` - Confirm a vulnerability as a real finding requiring remediation
  880. 276. `orbit_query` - Execute a GitLab Orbit graph query over the indexed SDLC knowledge graph
  881. 277. `orbit_get_schema` - Fetch the current GitLab Orbit graph schema (node and edge types)
  882. 278. `orbit_get_status` - Check GitLab Orbit indexing status for the enabled scope
  883. 279. `orbit_list_tools` - List the MCP tool definitions exposed by GitLab Orbit
  884. 280. `list_snippets` - List snippets — project snippets when project_id is given, otherwise personal snippets
  885. 281. `get_snippet` - Get a snippet's metadata. Set include_content=true to also fetch the raw file content.
  886. 282. `create_snippet` - Create a snippet — project-scoped when project_id is given, otherwise a personal snippet. Requires title plus either file_name + content (single file) or files[] (multi-file); the two shapes cannot be mixed.
  887. 283. `update_snippet` - Update an existing snippet (provide at least one field to change). For multi-file edits — renames, deletions, additions — pass files[] with action (create/update/delete/move) and previous_path. The file_name + content shortcut still works for single-file content replacement.
  888. 284. `delete_snippet` - Delete a snippet
  889. 285. `list_project_runners` - List runners available to a project (type, status, paused, tag_list). Omits registration and authentication tokens.
  890. 286. `get_runner` - Get a runner's tag_list, run_untagged, locked, and access_level. When a project allowlist is active, the runner must be available to an allowed project. Omits registration and authentication tokens.
  891. 287. `rebase_merge_request` - Rebase the source branch of a merge request onto its target branch
  892. 288. `gitlab_api_request` - Send one GitLab REST call under /api/v4. Enabled only when GITLAB_TOOLSETS lists api. Readonly allows GET; modify rejects DELETE.
  893. 289. `discover_tools` - List or activate a toolset for this session. Omit category to list; pass one to enable. Prefer this over GITLAB_TOOLSETS=all (loads ~all schemas). Session-only; with OAUTH_STATELESS_MODE=true persist GITLAB_TOOLSETS.
  894. 290. `help` - Return a short GitLab workflow guide. Omit topic for the overview and topic list.
  895. <!-- TOOLS-END -->
  896. </details>
  897. ### Wiki page titles vs. slugs
  898. GitLab derives a wiki page's **slug** (its URL, `/-/wikis/<slug>`) from the page title. Passing `title` to `update_wiki_page` / `update_group_wiki_page` therefore **renames the page and changes its URL** — for nested pages it can also move the page to a different path — which breaks existing links.
  899. To change only the **displayed title** while keeping the URL stable, do **not** pass `title`. Instead, store the display title in the page content's YAML front matter and update the content:
  900. ```markdown
  901. ---
  902. title: My Custom Display Title
  903. ---
  904. Page body…
  905. ```
  906. GitLab keeps the slug/URL untouched and shows the front-matter title in the UI. Read it back with `get_wiki_page` using `render_html: true`, which populates the `front_matter` field — the plain `title` field always reflects the slug-derived value.
  907. ## Testing 🧪
  908. The project includes comprehensive test coverage including remote authorization:
  909. ```bash
  910. # Run all tests (API validation + remote auth)
  911. npm test
  912. # Run only remote authorization tests
  913. npm run test:remote-auth
  914. # Run all tests including readonly MCP tests
  915. npm run test:all
  916. # Run only API validation
  917. npm run test:integration
  918. ```
  919. All remote authorization tests use a mock GitLab server and do not require actual GitLab credentials.
  920. ## Sponsor 💖
  921. Sponsorships through [GitHub Sponsors](https://github.com/sponsors/zereight) help cover GitLab E2E testing costs: a paid GitLab tier to test Premium/Ultimate features (such as milestone burndown charts and iterations) that the free test instance cannot reach, and the infrastructure for live API tests.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.