{
  "markdown": "# GitLab MCP Server\n\n[![GitHub stars](https://img.shields.io/github/stars/zereight/gitlab-mcp.svg?style=social&label=Star)](https://github.com/zereight/gitlab-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/@zereight/mcp-gitlab.svg)](https://www.npmjs.com/package/@zereight/mcp-gitlab)\n[![npm](https://img.shields.io/npm/v/@zereight/mcp-gitlab.svg)](https://www.npmjs.com/package/@zereight/mcp-gitlab)\n[![GitHub License](https://img.shields.io/github/license/zereight/gitlab-mcp.svg)](https://github.com/zereight/gitlab-mcp/blob/main/LICENSE)\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_GitLab_MCP-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22zereight.gitlab-mcp%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40zereight%2Fmcp-gitlab%40latest%22%5D%2C%22env%22%3A%7B%22GITLAB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agitlab-token%7D%22%2C%22GITLAB_API_URL%22%3A%22https%3A%2F%2Fgitlab.com%2Fapi%2Fv4%22%2C%22GITLAB_PERMISSION_MODE%22%3A%22full%22%7D%7D)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/zereight/gitlab-mcp)\n[![MCP Toplist](https://mcptoplist.com/badge/io.github.zereight%2Fgitlab-mcp.svg)](https://mcptoplist.com/server/io.github.zereight%2Fgitlab-mcp) [![mcpindex](https://mcpindex.ai/api/v1/badge/io-github-zereight-gitlab-mcp)](https://mcpindex.ai/server/io-github-zereight-gitlab-mcp)\n\n[English](./README.md) | [한국어](./README.ko.md) | [简体中文](./README.zh-CN.md) | [Português (Brasil)](./README.pt-BR.md)\n\n📖 **[Documentation →](https://zereight.github.io/gitlab-mcp/)** Setup guides, environment variables, and the full tool reference live on the hosted docs site.\n\n[![Star History Chart](./assets/star-history.png)](https://www.star-history.com/?repos=zereight%2Fgitlab-mcp&type=date&legend=top-left)\n\n## @zereight/mcp-gitlab\n\n**Agent-workflow-optimized GitLab MCP** — manage projects, merge requests, issues, pipelines, wiki, releases, tags, milestones, and more through stdio, SSE, and Streamable HTTP.\n\nSupports PAT, OAuth, read-only mode, dynamic API URLs, and remote authorization for VS Code, Claude, Cursor, Copilot, and other MCP clients.\n\n### Why use this GitLab MCP?\n\n- **266 tools + `discover_tools`** — start with a small toolset; activate more at runtime without CQRS-style grouping\n- **MR 2-step review** — `list_merge_request_changed_files` → batched `get_merge_request_file_diff`\n- **Agent Skill built in** — workflow guidance in `skills/gitlab-mcp/`\n- **Flexible auth** — Personal Access Token, local OAuth2 browser flow, MCP OAuth proxy, and per-request remote authorization\n- **Multiple transports** — stdio for local clients, SSE for legacy clients, and Streamable HTTP for modern remote deployments\n- **Client-friendly setup** — examples for Claude Code, Codex, Antigravity, OpenCode, Copilot, Cline, Roo Code, Cursor, Kilo Code, and Amp Code\n- **Self-hosted ready** — works with custom GitLab instances, proxy settings, and dynamic API URL routing\n- **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.\n\n### How we compare\n\n| | @zereight/mcp-gitlab | GitLab MCP A (community CQRS-style) |\n|---|----------------------|-------------------------------------|\n| **Best for** | AI agent workflows | Enterprise multi-instance / grouped tools |\n| **Tool model** | ~266 granular tools + `discover_tools` | ~50–60 grouped `browse_*` / `manage_*` tools |\n| **MR review** | 2-step batched diff | Varies |\n| **Node.js** | >=18.17 | Often >=24 |\n| **License** | MIT | Varies |\n\n[Full comparison →](./docs/comparison/community-gitlab-mcp-a.md)\n\nQuick start: choose either Personal Access Token or OAuth2 setup below, install `@zereight/mcp-gitlab`, and use `zereight-mcp-gitlab` in your MCP client configuration.\n\n### Client Setup Guides\n\n- [Claude Code Setup Guide](./docs/clients/claude-code.md)\n- [VS Code Setup Guide](./docs/clients/vscode.md)\n- [GitHub Copilot Setup Guide](./docs/clients/copilot.md)\n- [Codex Setup Guide](./docs/clients/codex.md)\n- [Cursor Setup Guide](./docs/clients/cursor.md)\n- [JSON-Based MCP Clients Setup Guide](./docs/clients/json-clients.md) - for Factory AI Droid, OpenClaw, and OpenCode style clients\n- [OAuth2 Authentication Setup Guide](./docs/auth/oauth-setup.md)\n- [Environment Variables Reference](./docs/configuration/environment-variables.md)\n- [Stateless Mode — Multi-Pod HPA](./docs/configuration/stateless-mode.md)\n- [Custom Agents and Multiple PAT Setup](./docs/auth/custom-agent-multiple-pat.md)\n\n## Usage\n\n### Setup Overview\n\n#### Authentication Methods\n\nThe server supports four authentication methods:\n\n**For local/desktop use** (most common):\n\n1. **Personal Access Token** (`GITLAB_PERSONAL_ACCESS_TOKEN`) — simplest setup\n2. **OAuth2 — Local Browser** (`GITLAB_USE_OAUTH`) — recommended for better security\n\n**For server/remote deployments**:\n\n3. **OAuth2 — MCP Proxy** (`GITLAB_MCP_OAUTH`) — for remote MCP clients such as Claude.ai\n4. **Remote Authorization** (`REMOTE_AUTHORIZATION`) — multi-user deployments where each caller provides their own token\n\n#### Quick setup paths\n\n- **Claude Code**: see [Claude Code Setup Guide](./docs/clients/claude-code.md)\n- **VS Code**: see [VS Code Setup Guide](./docs/clients/vscode.md)\n- **GitHub Copilot**: see [GitHub Copilot Setup Guide](./docs/clients/copilot.md)\n- **Codex**: see [Codex Setup Guide](./docs/clients/codex.md)\n- **Cursor**: see [Cursor Setup Guide](./docs/clients/cursor.md)\n- **Factory AI Droid / OpenClaw / OpenCode style clients**: see [JSON-Based MCP Clients Setup Guide](./docs/clients/json-clients.md)\n- **OAuth browser flow details**: see [OAuth2 Authentication Setup Guide](./docs/auth/oauth-setup.md)\n- **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).\n\nFor 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.\n\nInstall the server once:\n\n```shell\nbrew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp\nbrew install zereight/gitlab-mcp/zereight-mcp-gitlab\n```\n\nOr with npm:\n\n```shell\nnpm install -g @zereight/mcp-gitlab\n```\n\nOr with Nix, by adding this flake to your own:\n\n```nix\n# flake.nix\ninputs.gitlab-mcp.url = \"github:zereight/gitlab-mcp\";\n\n# wherever you configure your MCP client:\ncommand = lib.getExe inputs.gitlab-mcp.packages.${system}.default;\n```\n\nThe store path is pinned by your lock file; update it with `nix flake update gitlab-mcp`.\n\nThe 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`.\n\nNo global install? Pin `npx` to the previous stable release (the version these docs recommend), for example `npx -y @zereight/mcp-gitlab@2.1.67`. 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`).\n\n#### Using CLI Arguments (for clients with env var issues)\n\nSome MCP clients (like GitHub Copilot CLI) have issues with environment variables. Use CLI arguments instead:\n\n```json\n{\n  \"mcpServers\": {\n    \"gitlab\": {\n      \"command\": \"zereight-mcp-gitlab\",\n      \"args\": [\"--token=YOUR_GITLAB_TOKEN\", \"--api-url=https://gitlab.com/api/v4\"],\n      \"tools\": [\"*\"]\n    }\n  }\n}\n```\n\n**Available CLI arguments:**\n\n- `--token` - GitLab Personal Access Token (replaces `GITLAB_PERSONAL_ACCESS_TOKEN`)\n- `--api-url` - GitLab API URL (replaces `GITLAB_API_URL`)\n- `--read-only=true` - Enable read-only mode (replaces `GITLAB_READ_ONLY_MODE`, deprecated — prefer `--permission-mode=readonly`)\n- `--permission-mode` - Permission level: `readonly`, `modify` (no delete or teardown tools), or `full` (replaces `GITLAB_PERMISSION_MODE`, default `full`)\n- `--use-wiki=true` - Enable wiki API (replaces `USE_GITLAB_WIKI`, legacy — prefer `GITLAB_TOOLSETS=wiki`)\n- `--use-milestone=true` - Enable milestone API (replaces `USE_MILESTONE`, legacy — prefer `GITLAB_TOOLSETS=milestones`)\n- `--use-pipeline=true` - Enable pipeline API (replaces `USE_PIPELINE`, legacy — prefer `GITLAB_TOOLSETS=pipelines`)\n- `--disable-version-check=true` - Disable the startup new-version notice (replaces `GITLAB_DISABLE_VERSION_CHECK`)\n- `--masking-enabled=true` - Enable text-response masking (replaces `GITLAB_MASKING_ENABLED`)\n- `--masking-config` - Path to a masking configuration file (replaces `GITLAB_MASKING_CONFIG`)\n- `--masking-policy-file` - Path to a protected managed-policy file (replaces `GITLAB_MASKING_POLICY_FILE`)\n- `--masking-workspace-dir` - Directory used to resolve masking files (replaces `GITLAB_MASKING_WORKSPACE_DIR`)\n\nCLI arguments take precedence over environment variables.\n\n`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).\n\n> **Fine-grained tool filtering:** use `GITLAB_PERMISSION_MODE=modify` to allow create/update while\n> blocking every delete tool and the destructive teardown tools (`cancel_pipeline`,\n> `cancel_pipeline_job`, `stop_environment`, `stop_stale_environments`, `unprotect_branch`) —\n> including destructive mutations (deletion and teardown verbs) through `execute_graphql` and\n> `push_files` `delete`/`move` actions — or `GITLAB_PERMISSION_MODE=readonly` for read-only\n> access. You can also\n> enable toolset groups with `GITLAB_TOOLSETS=<group,…>`, allow-list individual tools with\n> `GITLAB_TOOLS=<tool,…>` (e.g. read-only groups plus a few specific write tools), and\n> deny-list by pattern with `GITLAB_DENIED_TOOLS_REGEX`. The legacy `USE_GITLAB_WIKI` /\n> `USE_MILESTONE` / `USE_PIPELINE` flags are kept for backward compatibility only.\n> See [Tools Reference](./docs/tools/index.md#feature-toggles) and\n> [Environment Variables](./docs/configuration/environment-variables.md).\n\n- sse\n\n```shell\ndocker run -i --rm \\\n  -e HOST=0.0.0.0 \\\n  -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \\\n  -e GITLAB_API_URL=\"https://gitlab.com/api/v4\" \\\n  -e GITLAB_PERMISSION_MODE=readonly \\\n  -e GITLAB_TOOLSETS=wiki,milestones,pipelines \\\n  -e SSE=true \\\n  -e SSE_AUTH_TOKEN=your_mcp_sse_token \\\n  -p 3333:3002 \\\n  zereight050/gitlab-mcp\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"gitlab\": {\n      \"type\": \"sse\",\n      \"url\": \"http://localhost:3333/sse\",\n      \"headers\": {\n        \"Authorization\": \"Bearer your_mcp_sse_token\"\n      }\n    }\n  }\n}\n```\n\n- streamable-http\n\n```shell\ndocker run -i --rm \\\n  -e HOST=0.0.0.0 \\\n  -e REMOTE_AUTHORIZATION=true \\\n  -e GITLAB_API_URL=\"https://gitlab.com/api/v4\" \\\n  -e GITLAB_PERMISSION_MODE=readonly \\\n  -e GITLAB_TOOLSETS=wiki,milestones,pipelines \\\n  -e STREAMABLE_HTTP=true \\\n  -p 3333:3002 \\\n  zereight050/gitlab-mcp\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"gitlab\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"http://localhost:3333/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer glpat-...\"\n      }\n    }\n  }\n}\n```\n\n#### Using MCP OAuth Proxy (`GITLAB_MCP_OAUTH`)\n\n> **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.\n\nFor remote MCP clients that support the MCP OAuth specification (e.g. Claude.ai).\nThe server acts as a full OAuth 2.0 authorization server — unauthenticated requests\nreceive a `401 + WWW-Authenticate` response, which triggers the OAuth browser flow\nautomatically on the client side.\n\nRemote MCP clients such as OpenCode, MCPJam, and Claude.ai can send their own\ncallback URL during authorization. If you cannot register every client callback\nURL in GitLab, enable `GITLAB_OAUTH_CALLBACK_PROXY=true`. With callback proxy\nmode, GitLab only needs one registered redirect URI: `{MCP_SERVER_URL}/callback`.\n\n`GITLAB_OAUTH_REDIRECT_URI` is for local OAuth (`GITLAB_USE_OAUTH`) only. It does\nnot override remote MCP OAuth client callback URLs and should not be used to fix\nremote `Unregistered redirect_uri` errors.\n\nThis variable exists because the local OAuth flow starts a browser on the same\nmachine as the MCP server and listens for the callback on a local HTTP server,\nfor example `http://127.0.0.1:8888/callback`.\n\nRemote MCP OAuth is different. In `GITLAB_MCP_OAUTH=true` mode, the MCP client\nprovides its own callback URL during `/authorize`. `GITLAB_OAUTH_REDIRECT_URI`\ndoes not replace that client-provided URL.\n\n| Mode             | Enable with             | Callback variable                  | GitLab redirect URI                                     |\n| ---------------- | ----------------------- | ---------------------------------- | ------------------------------------------------------- |\n| Local OAuth      | `GITLAB_USE_OAUTH=true` | `GITLAB_OAUTH_REDIRECT_URI`        | `http://127.0.0.1:8888/callback` or your local callback |\n| Remote MCP OAuth | `GITLAB_MCP_OAUTH=true` | `GITLAB_OAUTH_CALLBACK_PROXY=true` | `{MCP_SERVER_URL}/callback`                             |\n\nUse `GITLAB_OAUTH_REDIRECT_URI` only when the MCP server itself owns the local\nbrowser callback. Use `GITLAB_OAUTH_CALLBACK_PROXY=true` when a remote MCP client\nowns the callback URL.\n\n**How it works**: You deploy this MCP server somewhere with a public HTTPS URL. MCP\nclients connect to `{MCP_SERVER_URL}/mcp`. The server handles the OAuth 2.0 flow,\nexchanging credentials with GitLab on behalf of the client.\n\n**Prerequisites**:\n\n1. A publicly accessible HTTPS server URL (`MCP_SERVER_URL`) — use [ngrok](https://ngrok.com) for local testing\n2. A pre-registered GitLab OAuth application with `api` (or `read_api`) scopes\n   — Go to `Admin area` → `Applications`, set Redirect URI to `{MCP_SERVER_URL}/callback`\n\n| Environment Variable          | Required | Description                                                                                                                             |\n| ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |\n| `GITLAB_MCP_OAUTH`            | ✅       | Set to `true` to enable                                                                                                                 |\n| `GITLAB_API_URL`              | ✅       | GitLab API base URL                                                                                                                     |\n| `GITLAB_OAUTH_APP_ID`         | ✅       | GitLab OAuth Application ID                                                                                                             |\n| `MCP_SERVER_URL`              | ✅       | Public HTTPS URL of this MCP server                                                                                                     |\n| `STREAMABLE_HTTP`             | ✅       | Must be `true`                                                                                                                          |\n| `GITLAB_OAUTH_CALLBACK_PROXY` | optional | Set to `true` to use the MCP server's fixed `/callback` URL                                                                             |\n| `GITLAB_OAUTH_SCOPES`         | optional | Comma-separated scopes (default: `api,read_api,read_user`)                                                                              |\n| `GITLAB_OAUTH_ALLOWED_GROUPS` | optional | Comma-separated group full paths — only members (and subgroup members) may obtain a token (replaces deprecated `GITLAB_ALLOWED_GROUPS`) |\n\nWhen `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`.\n\n> **Troubleshooting `Unregistered redirect_uri`**\n>\n> Check the `redirect_uri` in the browser URL. If it points to a client callback\n> such as `http://127.0.0.1:xxxxx/.../callback`, enable:\n>\n> ```env\n> GITLAB_OAUTH_CALLBACK_PROXY=true\n> ```\n>\n> Do not fix remote MCP OAuth by changing `GITLAB_OAUTH_REDIRECT_URI`. That\n> variable is for local OAuth (`GITLAB_USE_OAUTH`) only.\n\n```shell\ndocker run -i --rm \\\n  -e HOST=0.0.0.0 \\\n  -e GITLAB_MCP_OAUTH=true \\\n  -e GITLAB_OAUTH_CALLBACK_PROXY=true \\\n  -e STREAMABLE_HTTP=true \\\n  -e MCP_SERVER_URL=https://your-server.example.com \\\n  -e GITLAB_API_URL=\"https://gitlab.com/api/v4\" \\\n  -e GITLAB_OAUTH_APP_ID=your_app_id \\\n  -p 3000:3002 \\\n  zereight050/gitlab-mcp\n```\n\nMCP client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"gitlab\": {\n      \"type\": \"http\",\n      \"url\": \"https://your-server.example.com/mcp\"\n    }\n  }\n}\n```\n\n#### Using Remote Authorization (`REMOTE_AUTHORIZATION`)\n\n> **For server/remote deployments only.** Each HTTP caller provides their own GitLab token directly in request headers — no OAuth flow involved.\n\nFor multi-user or multi-tenant deployments where each caller provides their own\nGitLab token in the HTTP request header. No OAuth flow — the MCP server forwards\nthe token to GitLab on behalf of the caller.\n\n**Header priority**: `Private-Token` > `JOB-TOKEN` > `Authorization: Bearer`\n\n| Environment Variable                          | Required | Description                                                                                                             |\n| --------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `REMOTE_AUTHORIZATION`                        | ✅       | Set to `true` to enable                                                                                                 |\n| `STREAMABLE_HTTP`                             | ✅       | Must be `true`                                                                                                          |\n| `ENABLE_DYNAMIC_API_URL`                      | optional | Allow per-request GitLab URL via `X-GitLab-API-URL` header                                                              |\n| `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 |\n| `GITLAB_ALLOW_UNAUTHENTICATED_TOOL_DISCOVERY` | optional | Allow unauthenticated `initialize`, `notifications/initialized`, `tools/list`, and `server/discover` only (tool calls still require auth)  |\n| `MCP_SERVER_URL` / `MCP_ALLOWED_HOSTS` / `MCP_ALLOWED_ORIGINS` | optional | Allowed public `/mcp` host/origin values for DNS rebinding protection                                   |\n| `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) |\n\n`GITLAB_ALLOW_UNAUTHENTICATED_TOOL_DISCOVERY=true` is intended for MCP gateways\nor admin UIs that need to inspect tool metadata before a user provides a GitLab\ntoken. Leave it disabled unless the tool list is safe to expose in your deployment.\n\nWhen `MCP_SERVER_URL` is not set, remote download URLs fall back to the local\nserver address. Set `MCP_TRUST_PROXY=true` only if the server is reachable through a\ntrusted reverse proxy and direct client access to the MCP server is blocked.\nThis enables Express `trust proxy` for Streamable HTTP and SSE, derives public\ndownload URLs from `Forwarded` / `X-Forwarded-Proto` / `X-Forwarded-Host` /\n`X-Forwarded-Prefix`, and keeps OAuth endpoint rate limiting working when\nproxies send `X-Forwarded-For` with a client port (for example `1.2.3.4:5678`).\nExisting OAuth+proxy deployments must set this explicitly after the flag was\nintroduced.\n\n**Example request headers**:\n\n```http\nPrivate-Token: glpat-xxxxxxxxxxxxxxxxxxxx\n```\n\nor using a Bearer token:\n\n```http\nAuthorization: Bearer glpat-xxxxxxxxxxxxxxxxxxxx\n```\n\n> ⚠️ `REMOTE_AUTHORIZATION` is **not compatible** with SSE transport. `STREAMABLE_HTTP=true` is required.\n\n### Environment Variables\n\nUse the dedicated reference for the full environment variable list:\n\n- [Environment Variables Reference](./docs/configuration/environment-variables.md)\n\nMost users only need one of these starting sets:\n\n- **Local PAT**: `GITLAB_PERSONAL_ACCESS_TOKEN`, `GITLAB_API_URL`\n- **Local OAuth**: `GITLAB_USE_OAUTH=true`, `GITLAB_OAUTH_CLIENT_ID`, `GITLAB_OAUTH_REDIRECT_URI`, `GITLAB_API_URL`\n- **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`\n- **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\n- **Multi-pod HPA (stateless)**: above + `OAUTH_STATELESS_MODE=true`, `OAUTH_STATELESS_SECRET` (same across all pods). See [Stateless Mode](./docs/configuration/stateless-mode.md).\n\nCommonly referenced variables:\n\n- `GITLAB_API_URL`\n- `GITLAB_PERSONAL_ACCESS_TOKEN`\n- `GITLAB_USE_OAUTH`\n- `REMOTE_AUTHORIZATION`\n- `MCP_TRUST_PROXY`\n- `MAX_REQUESTS_PER_MINUTE`\n- `MAX_SESSIONS`\n- `MCP_ALLOWED_HOSTS`\n- `MCP_ALLOWED_ORIGINS`\n- `GITLAB_MCP_OAUTH`\n- `GITLAB_OAUTH_CALLBACK_PROXY`\n- `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR`\n- `OAUTH_STATELESS_MODE`\n- `OAUTH_STATELESS_SECRET`\n\nThe reference document also covers:\n\n- auth and OAuth variables\n- MCP OAuth proxy variables\n- project and tool filtering variables\n- dynamic tool discovery via `discover_tools` (on-demand toolset activation)\n- transport and session variables\n- proxy and TLS variables\n\nFor callback proxy mode details, see [GitLab MCP OAuth Callback Proxy](./docs/auth/oauth-callback-proxy.md).\n\n#### SSE session limits\n\n`GET /sse` is subject to the same remote-transport controls as Streamable HTTP:\n\n- **Capacity:** at most `MAX_SESSIONS` concurrent SSE sessions (default 1000); further connections get `503`.\n- **Creation rate limit:** new connections are limited to `MAX_REQUESTS_PER_MINUTE` per client IP (default 60); excess connections get `429`.\n- **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.\n- `/health` returns `503` with `status: \"degraded\"` while the instance is at capacity.\n\nTune these with [`MAX_SESSIONS`](./docs/configuration/environment-variables.md#max_sessions), `MAX_REQUESTS_PER_MINUTE`, and `SESSION_TIMEOUT_SECONDS`.\n\n### Remote Authorization Setup (Multi-User Support)\n\nWhen 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:\n\n- Shared MCP server instances where each user needs their own GitLab access\n- IDE integrations that can inject user-specific tokens into MCP requests\n\n**Setup Example:**\n\n```bash\n# Start server with remote authorization\ndocker run -d \\\n  -e HOST=0.0.0.0 \\\n  -e STREAMABLE_HTTP=true \\\n  -e REMOTE_AUTHORIZATION=true \\\n  -e GITLAB_API_URL=\"https://gitlab.com/api/v4\" \\\n  -e GITLAB_PERMISSION_MODE=readonly \\\n  -e SESSION_TIMEOUT_SECONDS=3600 \\\n  -p 3333:3002 \\\n  zereight050/gitlab-mcp\n```\n\n**Client Configuration:**\n\nYour IDE or MCP client must send one of these headers with each request:\n\n```\nAuthorization: Bearer glpat-xxxxxxxxxxxxxxxxxxxx\n```\n\nor\n\n```\nPrivate-Token: glpat-xxxxxxxxxxxxxxxxxxxx\n```\n\nThe token is stored per session (identified by `mcp-session-id` header) and reused for subsequent requests in the same session.\n\n#### Remote Authorization Client Configuration Example with Cursor\n\n```json\n{\n  \"mcpServers\": {\n    \"GitLab\": {\n      \"url\": \"http(s)://<your_mcp_gitlab_server>/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer glpat-...\"\n      }\n    }\n  }\n}\n```\n\n**Important Notes:**\n\n- Remote authorization **only works with Streamable HTTP transport**\n- Each session is isolated - tokens from one session cannot access another session's data\n  Tokens are automatically cleaned up when sessions close\n- **Session timeout:** Auth tokens expire after `SESSION_TIMEOUT_SECONDS` (default 1 hour) of inactivity. After timeout, the client must send auth headers again. The transport session remains active.\n- Each request resets the timeout timer for that session\n- **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). See [environment-variables.md](docs/configuration/environment-variables.md#max_requests_per_minute).\n- **Capacity limit:** Server accepts up to `MAX_SESSIONS` concurrent sessions (default 1000)\n\n### MCP OAuth Setup (Claude.ai Native OAuth)\n\nWhen using `GITLAB_MCP_OAUTH=true`, the server acts as an OAuth proxy to your GitLab\ninstance. Claude.ai (and any MCP-spec-compliant client) handles the entire browser\nauthentication flow automatically — no manual Personal Access Token management needed.\n\n**Prerequisites:**\n\nA **pre-registered GitLab OAuth application** is required. GitLab restricts dynamically\nregistered (unverified) applications to the `mcp` scope, which is insufficient for API\ncalls (need `api` or `read_api`).\n\n1. Go to your GitLab instance → **Admin Area > Applications** (instance-wide) or **User Settings > Applications** (personal)\n2. Create a new application with:\n   - **Confidential**: unchecked\n   - **Scopes**: `api`, `read_api`, `read_user` (or whichever scopes you intend to request via `GITLAB_OAUTH_SCOPES`)\n3. Save and copy the **Application ID** — this is your `GITLAB_OAUTH_APP_ID`\n\n**How it works:**\n\n1. User adds your MCP server URL in Claude.ai\n2. Claude.ai discovers OAuth endpoints via `/.well-known/oauth-authorization-server`\n3. Claude.ai registers itself via Dynamic Client Registration (`POST /register`) — handled locally by the MCP server (each client gets a virtual client ID)\n4. Claude.ai redirects the user's browser to GitLab's login page using the pre-registered OAuth application\n5. User authenticates; GitLab redirects back to `https://claude.ai/api/mcp/auth_callback`\n6. Claude.ai sends `Authorization: Bearer <token>` on every MCP request\n7. Server validates the token with GitLab and stores it per session\n\n**Server setup:**\n\n```bash\ndocker run -d \\\n  -e STREAMABLE_HTTP=true \\\n  -e GITLAB_MCP_OAUTH=true \\\n  -e GITLAB_OAUTH_APP_ID=\"your-gitlab-oauth-app-client-id\" \\\n  -e GITLAB_API_URL=\"https://gitlab.example.com/api/v4\" \\\n  -e MCP_SERVER_URL=\"https://your-mcp-server.example.com\" \\\n  -p 3002:3002 \\\n  zereight050/gitlab-mcp\n```\n\nFor local development (HTTP allowed):\n\n```bash\nMCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL=true \\\nSTREAMABLE_HTTP=true \\\nGITLAB_MCP_OAUTH=true \\\nGITLAB_OAUTH_APP_ID=your-gitlab-oauth-app-client-id \\\nMCP_SERVER_URL=http://localhost:3002 \\\nGITLAB_API_URL=https://gitlab.com/api/v4 \\\nnode build/index.js\n```\n\n**Claude.ai configuration:**\n\n```json\n{\n  \"mcpServers\": {\n    \"GitLab\": {\n      \"url\": \"https://your-mcp-server.example.com/mcp\"\n    }\n  }\n}\n```\n\nNo `headers` field is needed — Claude.ai obtains the token via OAuth automatically.\n\n**Environment variables:**\n\n| Variable                                    | Required | Description                                                                                                                                                                                                         |\n| ------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `GITLAB_MCP_OAUTH`                          | Yes      | Set to `true` to enable                                                                                                                                                                                             |\n| `GITLAB_OAUTH_APP_ID`                       | Yes      | Client ID of the pre-registered GitLab OAuth application                                                                                                                                                            |\n| `MCP_SERVER_URL`                            | Yes      | Public HTTPS URL of your MCP server; also allowed for `/mcp` Host/Origin checks                                                                                                                                     |\n| `GITLAB_API_URL`                            | Yes      | Your GitLab instance API URL (e.g. `https://gitlab.com/api/v4`)                                                                                                                                                     |\n| `STREAMABLE_HTTP`                           | Yes      | Must be `true` (SSE is not supported)                                                                                                                                                                               |\n| `GITLAB_OAUTH_SCOPES`                       | No       | Comma-separated GitLab scopes to request (e.g. `api,read_user`). Defaults to `api` (or `read_api` when `GITLAB_READ_ONLY_MODE=true`). The pre-registered application must be configured with at least these scopes. |\n| `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR`        | No       | Per-IP rolling limit 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. |\n| `MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL` | No       | Set `true` for local HTTP dev only                                                                                                                                                                                  |\n\n**Important Notes:**\n\n- MCP OAuth **only works with Streamable HTTP transport** (`SSE=true` is incompatible)\n- Each user session stores its own OAuth token — sessions are fully isolated\n- Session timeout, rate limiting, and capacity limits apply identically to the\n  `REMOTE_AUTHORIZATION` mode (`SESSION_TIMEOUT_SECONDS`, `MAX_REQUESTS_PER_MINUTE`,\n  `MAX_SESSIONS`)\n- **DCR rate limiting:** `POST /register` is limited to `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR`\n  per client IP (default 20/hour). Separate from `/mcp` limits and GitLab API quotas.\n  See [environment-variables.md](docs/configuration/environment-variables.md#oauth_register_rate_limit_per_hour).\n- **Header auth fallback:** when `Private-Token` or `JOB-TOKEN` request headers are\n  present, OAuth validation is skipped and the raw token is used directly for that\n  session. This allows PATs and CI job tokens to be used alongside the OAuth flow on\n  the same server instance. `Authorization: Bearer` is always treated as an OAuth\n  token — use `Private-Token` for PAT-based header auth.\n\n## Agent Skill Files\n\nPre-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.).\n\n- **[SKILL.md](./skills/gitlab-mcp/SKILL.md)** — Core guide (~800 tokens) with toolset overview, key workflows, and parameter hints\n- **[reference/](./skills/gitlab-mcp/reference/)** — Detailed workflow docs for code review, merge requests, issues, pipelines, and vulnerability triage\n\nInstall with the `skills` CLI:\n\n```bash\nnpx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill\n```\n\nRegister the skill directory in your AI client to get optimal tool usage guidance without relying solely on the full ListTools response.\n\n## Tools 🛠️\n\n<details>\n<summary>Click to expand</summary>\n\n<!-- TOOLS-START -->\n\n1. `merge_merge_request` - Merge a merge request\n2. `approve_merge_request` - Approve a merge request\n3. `unapprove_merge_request` - Unapprove a merge request\n4. `get_merge_request_approval_state` - Get merge request approval details including approvers\n5. `get_merge_request_conflicts` - Get the conflicts of a merge request\n6. `list_merge_request_pipelines` - List pipelines for a merge request with pagination\n7. `execute_graphql` - Execute a GitLab GraphQL query\n8. `create_or_update_file` - Create or update a file in a GitLab project\n9. `search_repositories` - Search for GitLab projects\n10. `create_repository` - Create a new GitLab project\n11. `create_group` - Create new group or subgroup\n12. `get_file_contents` - Get contents of a file or directory from a GitLab project\n13. `push_files` - Push multiple files in a single commit\n14. `create_issue` - Create a new issue\n15. `create_merge_request` - Create a new merge request\n16. `fork_repository` - Fork a project to your account or specified namespace\n17. `create_branch` - Create a new branch\n18. `get_branch` - Get branch details (commit, protection status)\n19. `list_branches` - List branches in project with search filter\n20. `delete_branch` - Delete branch from project\n21. `list_protected_branches` - List protected branches in a project, supports search filter\n22. `get_protected_branch` - Get details of a single protected branch (access levels, force push settings)\n23. `protect_branch` - Protect a repository branch (set push/merge/unprotect access levels)\n24. `unprotect_branch` - Remove protection from a previously protected branch\n25. `update_default_branch` - Change the default branch of a project\n26. `get_merge_request` - Get details of a merge request (mergeRequestIid or branchName required). Set include_summaries=true for deployment/commit/approval summaries\n27. `get_merge_request_diffs` - Get the changes/diffs of a merge request (mergeRequestIid or branchName required)\n28. `list_merge_request_changed_files` - List changed file paths in a merge request without diff content (mergeRequestIid or branchName required)\n29. `list_merge_request_diffs` - List merge request diffs with pagination (mergeRequestIid or branchName required)\n30. `get_merge_request_file_diff` - Get diffs for specific files from a merge request (mergeRequestIid or branchName required)\n31. `list_merge_request_versions` - List all versions of a merge request\n32. `get_merge_request_version` - Get a specific version of a merge request\n33. `get_branch_diffs` - Get diffs between two branches or commits\n34. `update_merge_request` - Update a merge request (mergeRequestIid or branchName required)\n35. `create_note` - Create a new note (comment) to an issue or merge request\n36. `create_merge_request_thread` - Create a new thread on a merge request\n37. `resolve_merge_request_thread` - Resolve a thread on a merge request\n38. `mr_discussions` - List discussion items for a merge request\n39. `delete_merge_request_discussion_note` - Delete a discussion note on a merge request\n40. `update_merge_request_discussion_note` - Update a discussion note on a merge request\n41. `create_merge_request_discussion_note` - Add a new discussion note to an existing merge request thread\n42. `create_merge_request_note` - Add a new note to a merge request\n43. `delete_merge_request_note` - Delete an existing merge request note\n44. `get_merge_request_note` - Get a specific note for a merge request\n45. `get_merge_request_notes` - List notes for a merge request\n46. `update_merge_request_note` - Modify an existing merge request note\n47. `get_draft_note` - Get a single draft note from a merge request\n48. `list_draft_notes` - List draft notes for a merge request\n49. `create_draft_note` - Create a draft note for a merge request\n50. `update_draft_note` - Update an existing draft note\n51. `delete_draft_note` - Delete a draft note\n52. `publish_draft_note` - Publish a single draft note\n53. `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.\n54. `list_merge_request_emoji_reactions` - List all emoji reactions on a merge request\n55. `list_merge_request_note_emoji_reactions` - List all emoji reactions on a merge request note. Pass discussion_id for discussion thread replies.\n56. `create_merge_request_emoji_reaction` - Add an emoji reaction to a merge request (e.g. thumbsup, rocket, eyes)\n57. `delete_merge_request_emoji_reaction` - Remove an emoji reaction from a merge request\n58. `create_merge_request_note_emoji_reaction` - Add an emoji reaction to a merge request note. Pass discussion_id for discussion thread replies.\n59. `delete_merge_request_note_emoji_reaction` - Remove an emoji reaction from a merge request note. Pass discussion_id for discussion thread replies.\n60. `update_issue_note` - Modify an existing issue thread note\n61. `create_issue_note` - Add a note to an issue, optionally replying to a discussion thread\n62. `list_issue_emoji_reactions` - List all emoji reactions on an issue\n63. `list_issue_note_emoji_reactions` - List all emoji reactions on an issue note. Pass discussion_id for discussion thread replies.\n64. `create_issue_emoji_reaction` - Add an emoji reaction to an issue (e.g. thumbsup, rocket, eyes)\n65. `delete_issue_emoji_reaction` - Remove an emoji reaction from an issue\n66. `create_issue_note_emoji_reaction` - Add an emoji reaction to an issue note. Pass discussion_id for discussion thread replies.\n67. `delete_issue_note_emoji_reaction` - Remove an emoji reaction from an issue note. Pass discussion_id for discussion thread replies.\n68. `list_issues` - List issues (default: created by current user; use scope='all' for all)\n69. `my_issues` - List issues assigned to the authenticated user\n70. `get_issue` - Get details of a specific issue. Returns a slim milestone by default; set full_response=true for the complete milestone object\n71. `update_issue` - Update an issue. Returns a slim confirmation by default; set full_response=true for the complete updated issue object\n72. `update_issue_description_patch` - Apply a patch (search/replace or unified diff) to an issue description. Reduces token usage by allowing small changes without sending the full description. Supports dry_run to preview changes and create_note to summarize updates.\n73. `delete_issue` - Delete an issue\n74. `list_todos` - List GitLab to-do items for the current user\n75. `mark_todo_done` - Mark a GitLab to-do item as done\n76. `mark_all_todos_done` - Mark all pending GitLab to-do items as done for the current user\n77. `list_issue_links` - List all issue links for a specific issue\n78. `list_issue_discussions` - List discussions for an issue\n79. `get_issue_link` - Get a specific issue link\n80. `create_issue_link` - Create an issue link between two issues\n81. `delete_issue_link` - Delete an issue link\n82. `list_namespaces` - List all namespaces (users and groups) available to the current user. Filter by kind='group' for groups only.\n83. `get_namespace` - Get details of a namespace (user or group) by ID or path. Groups are namespaces with kind='group'.\n84. `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.\n85. `get_project` - Get details of a specific project\n86. `list_projects` - List projects accessible by the current user\n87. `update_project` - Update project settings such as description, visibility, default branch, and feature access levels\n88. `list_project_members` - List members of a GitLab project\n89. `list_group_members` - List members of a GitLab group with optional name or username search\n90. `list_labels` - List labels for a project\n91. `get_label` - Get a single label from a project\n92. `create_label` - Create a new label in a project\n93. `update_label` - Update an existing label in a project\n94. `delete_label` - Delete a label from a project\n95. `list_group_projects` - List projects in a group\n96. `list_wiki_pages` - List wiki pages in a project\n97. `get_wiki_page` - Get details of a specific wiki page\n98. `create_wiki_page` - Create a wiki page in a project\n99. `update_wiki_page` - Update a wiki page in a project\n100. `delete_wiki_page` - Delete a wiki page from a project\n101. `list_group_wiki_pages` - List wiki pages in a group\n102. `get_group_wiki_page` - Get details of a specific group wiki page\n103. `create_group_wiki_page` - Create a wiki page in a group\n104. `update_group_wiki_page` - Update a wiki page in a group\n105. `delete_group_wiki_page` - Delete a wiki page from a group\n106. `get_repository_tree` - List files and directories in a repository\n107. `list_pipelines` - List pipelines with filtering options\n108. `get_pipeline` - Get details of a specific pipeline\n109. `get_pipeline_variables` - Get variables configured for a pipeline\n110. `get_pipeline_test_report` - Get pipeline test report\n111. `get_pipeline_test_report_summary` - Get pipeline test report summary\n112. `delete_pipeline` - Delete a pipeline. Requires the project Owner role, cannot be undone, and does not automatically delete child pipelines.\n113. `update_pipeline_metadata` - Update pipeline metadata\n114. `list_deployments` - List deployments with filtering options\n115. `get_deployment` - Get deployment details, including approval_summary, approvals, and pending_approval_count when GitLab provides them\n116. `create_deployment` - Create a deployment\n117. `update_deployment` - Update a deployment status\n118. `delete_deployment` - Delete a deployment\n119. `list_deployment_merge_requests` - List merge requests shipped with a deployment\n120. `approve_deployment` - Approve or reject a protected-environment deployment\n121. `list_environments` - List environments in a project\n122. `get_environment` - Get details of a specific environment\n123. `update_environment` - Update an environment\n124. `delete_environment` - Delete a stopped environment\n125. `stop_environment` - Stop an environment\n126. `stop_stale_environments` - Stop eligible stale environments; protected environments are excluded and environments are stopped, not deleted\n127. `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\n128. `list_pipeline_triggers` - List project pipeline trigger tokens\n129. `get_pipeline_trigger` - Get a project pipeline trigger\n130. `create_pipeline_trigger` - Create a project pipeline trigger\n131. `update_pipeline_trigger` - Update a project pipeline trigger\n132. `delete_pipeline_trigger` - Delete a project pipeline trigger\n133. `trigger_pipeline` - Trigger a pipeline with a pipeline trigger token\n134. `list_pipeline_jobs` - List all jobs in a specific pipeline\n135. `list_pipeline_trigger_jobs` - List trigger jobs (bridges) in a pipeline\n136. `get_pipeline_job` - Get details of a GitLab pipeline job number\n137. `get_pipeline_job_output` - Get the output/trace of a pipeline job with optional pagination\n138. `validate_ci_lint` - Validate provided GitLab CI/CD YAML content for a project\n139. `validate_project_ci_lint` - Validate an existing .gitlab-ci.yml configuration for a project\n140. `list_ci_catalog_resources` - List GitLab CI/CD Catalog resources/components visible to the user\n141. `get_ci_catalog_resource` - Get details for a GitLab CI/CD Catalog resource, including versions and components\n142. `create_pipeline` - Create a new pipeline for a branch or tag\n143. `retry_pipeline` - Retry a failed or canceled pipeline\n144. `cancel_pipeline` - Cancel a running pipeline\n145. `list_pipeline_schedules` - List pipeline schedules in a project, optionally filtered to active or inactive\n146. `get_pipeline_schedule` - Get details of a specific pipeline schedule, including its variables and last pipeline\n147. `list_pipeline_schedule_pipelines` - List the pipelines that a pipeline schedule has triggered\n148. `create_pipeline_schedule` - Create a new pipeline schedule for a branch or tag\n149. `update_pipeline_schedule` - Update an existing pipeline schedule\n150. `delete_pipeline_schedule` - Delete a pipeline schedule\n151. `play_pipeline_schedule` - Run a pipeline schedule immediately\n152. `take_ownership_pipeline_schedule` - Take ownership of a pipeline schedule\n153. `get_pipeline_schedule_variable` - Get a single variable of a pipeline schedule\n154. `create_pipeline_schedule_variable` - Create a variable for a pipeline schedule\n155. `update_pipeline_schedule_variable` - Update a variable of a pipeline schedule\n156. `delete_pipeline_schedule_variable` - Delete a variable from a pipeline schedule\n157. `play_pipeline_job` - Run a manual pipeline job\n158. `play_pipeline_jobs` - Play multiple manual pipeline jobs sequentially\n159. `retry_pipeline_job` - Retry a failed or canceled pipeline job\n160. `cancel_pipeline_job` - Cancel a running pipeline job\n161. `erase_pipeline_job` - Erase a pipeline job log and artifacts\n162. `wait_for_pipeline` - Wait for a pipeline to reach a terminal status\n163. `wait_for_job` - Wait for a job to reach a terminal status\n164. `list_job_artifacts` - List artifact files in a job's archive\n165. `download_job_artifacts` - Download job artifact archive (zip) and save to a local path\n166. `get_job_artifact_file` - Get content of a single file from a job's artifacts\n167. `list_merge_requests` - List merge requests (without project_id: user's MRs; with project_id: project MRs)\n168. `list_group_merge_requests` - List merge requests across all projects of a group and its subgroups\n169. `list_milestones` - List milestones with filtering options\n170. `get_milestone` - Get details of a specific milestone\n171. `create_milestone` - Create a new milestone\n172. `edit_milestone` - Edit an existing milestone\n173. `delete_milestone` - Delete a milestone\n174. `get_milestone_issue` - Get issues associated with a specific milestone\n175. `get_milestone_merge_requests` - Get merge requests associated with a specific milestone\n176. `promote_milestone` - Promote a milestone to the next stage\n177. `get_milestone_burndown_events` - Get burndown events for a specific milestone\n178. `list_group_milestones` - List group milestones with filtering options\n179. `get_group_milestone` - Get details of a specific group milestone\n180. `create_group_milestone` - Create a new group milestone\n181. `edit_group_milestone` - Edit an existing group milestone\n182. `delete_group_milestone` - Delete a group milestone\n183. `get_group_milestone_issue` - Get issues associated with a specific group milestone\n184. `get_group_milestone_merge_requests` - Get merge requests associated with a specific group milestone\n185. `get_group_milestone_burndown_events` - Get burndown events for a specific group milestone\n186. `get_users` - Get GitLab user details by usernames\n187. `get_user` - Get user details by ID\n188. `whoami` - Get current authenticated user details\n189. `list_commits` - List repository commits with filtering options\n190. `get_commit` - Get details of a specific commit\n191. `get_commit_diff` - Get changes/diffs of a specific commit\n192. `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.\n193. `list_commit_statuses` - List statuses for a commit\n194. `create_commit_status` - Create or update the status of a commit\n195. `list_group_iterations` - List group iterations with filtering options\n196. `upload_markdown` - Upload a file for use in markdown content\n197. `download_attachment` - Download an uploaded file from a project (images returned as base64; use local_path to save to disk)\n198. `health_check` - Verify server status and authentication. Always reports the MCP server version (mcp_server_version). When authenticated, also reports the GitLab instance version from GET /api/v4/version (version, revision, enterprise). Version lookup failures do not fail the health check — those fields are omitted.\n199. `list_events` - List events for the authenticated user (before/after: YYYY-MM-DD)\n200. `get_project_events` - List events for a project (before/after: YYYY-MM-DD)\n201. `list_releases` - List all releases for a project\n202. `get_release` - Get a release by tag name\n203. `create_release` - Create a new release\n204. `update_release` - Update an existing release\n205. `delete_release` - Delete a release (does not delete the tag)\n206. `create_release_evidence` - Create release evidence (Premium/Ultimate)\n207. `download_release_asset` - Download a release asset file by direct asset path\n208. `list_tags` - List repository tags for a project\n209. `get_tag` - Get a repository tag by name\n210. `create_tag` - Create a new repository tag\n211. `delete_tag` - Delete a repository tag\n212. `get_tag_signature` - Get the X.509 signature of a signed tag (404 if unsigned)\n213. `get_work_item` - Get a work item with full details including status, hierarchy, type, and widgets\n214. `list_work_items` - List work items with filters (type, state, search, assignees, labels)\n215. `create_work_item` - Create a work item (issue, task, incident, epic, etc.) with full field support\n216. `update_work_item` - Update a work item (title, description, labels, assignees, state, parent, custom fields, etc.)\n217. `convert_work_item_type` - Convert a work item to a different type\n218. `list_work_item_statuses` - List available statuses for a work item type (Premium/Ultimate)\n219. `list_custom_field_definitions` - List custom field definitions for a work item type\n220. `move_work_item` - Move a work item to a different project\n221. `list_work_item_notes` - List notes and discussions on a work item\n222. `create_work_item_note` - Add a note to a work item (supports Markdown, internal notes, threads)\n223. `list_work_item_emoji_reactions` - List all emoji reactions on a work item\n224. `list_work_item_note_emoji_reactions` - List all emoji reactions on a work item note (comment, thread, or thread reply)\n225. `create_work_item_emoji_reaction` - Add an emoji reaction to a work item (e.g. thumbsup, rocket, eyes)\n226. `delete_work_item_emoji_reaction` - Remove an emoji reaction from a work item\n227. `create_work_item_note_emoji_reaction` - Add an emoji reaction to a work item note (comment, thread, or thread reply)\n228. `delete_work_item_note_emoji_reaction` - Remove an emoji reaction from a work item note (comment, thread, or thread reply)\n229. `get_timeline_events` - List timeline events for an incident\n230. `create_timeline_event` - Create a timeline event on an incident\n231. `list_webhooks` - List webhooks for a project or group\n232. `create_webhook` - Create a webhook on a project or group\n233. `update_webhook` - Update an existing project or group webhook\n234. `delete_webhook` - Delete a project or group webhook\n235. `list_webhook_events` - List recent webhook events (past 7 days)\n236. `get_webhook_event` - Get full details of a specific webhook event\n237. `search_code` - Search for code across all projects (requires advanced search or Zoekt)\n238. `search_project_code` - Search for code within a specific project (requires advanced search or Zoekt)\n239. `search_group_code` - Search for code within a specific group (requires advanced search or Zoekt)\n240. `list_project_variables` - List CI/CD variables for a project\n241. `get_project_variable` - Get a single CI/CD variable from a project\n242. `create_project_variable` - Create a CI/CD variable for a project\n243. `update_project_variable` - Update an existing CI/CD variable in a project\n244. `delete_project_variable` - Delete a CI/CD variable from a project\n245. `list_group_variables` - List CI/CD variables for a group\n246. `get_group_variable` - Get a single CI/CD variable from a group\n247. `create_group_variable` - Create a CI/CD variable for a group\n248. `update_group_variable` - Update an existing CI/CD variable in a group\n249. `delete_group_variable` - Delete a CI/CD variable from a group\n250. `get_dependency_proxy_settings` - Get dependency proxy settings for a group\n251. `update_dependency_proxy_settings` - Update dependency proxy settings for a group (enable/disable, credentials for authenticated Docker Hub pulls)\n252. `list_dependency_proxy_blobs` - List cached dependency proxy blobs for a group\n253. `purge_dependency_proxy_cache` - Schedule purge of all cached dependency proxy blobs for a group\n254. `list_project_vulnerabilities` - List vulnerabilities for a project with optional state, severity, and report type filters (GraphQL-backed, cursor pagination)\n255. `get_vulnerability` - Get full details of a specific vulnerability\n256. `dismiss_vulnerability` - Dismiss a vulnerability with a reason (acceptable_risk, false_positive, used_in_tests, mitigating_control, not_applicable) and optional comment\n257. `confirm_vulnerability` - Confirm a vulnerability as a real finding requiring remediation\n258. `orbit_query` - Execute a GitLab Orbit graph query over the indexed SDLC knowledge graph\n259. `orbit_get_schema` - Fetch the current GitLab Orbit graph schema (node and edge types)\n260. `orbit_get_status` - Check GitLab Orbit indexing status for the enabled scope\n261. `orbit_list_tools` - List the MCP tool definitions exposed by GitLab Orbit\n262. `list_snippets` - List snippets — project snippets when project_id is given, otherwise personal snippets\n263. `get_snippet` - Get a snippet's metadata. Set include_content=true to also fetch the raw file content.\n264. `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.\n265. `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.\n266. `delete_snippet` - Delete a snippet\n267. `discover_tools` - Discover and activate additional tool categories for this session. Available categories: merge_requests, issues, repositories, branches, projects, labels, ci, groups, pipelines, milestones, wiki, releases, tags, snippets, users, workitems, webhooks, search, variables, dependency_proxy, vulnerabilities, orbit. Already-active categories are listed in the response.\n\n<!-- TOOLS-END -->\n\n</details>\n\n### Wiki page titles vs. slugs\n\nGitLab 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.\n\nTo 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:\n\n```markdown\n---\ntitle: My Custom Display Title\n---\n\nPage body…\n```\n\nGitLab 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.\n\n## Testing 🧪\n\nThe project includes comprehensive test coverage including remote authorization:\n\n```bash\n# Run all tests (API validation + remote auth)\nnpm test\n\n# Run only remote authorization tests\nnpm run test:remote-auth\n\n# Run all tests including readonly MCP tests\nnpm run test:all\n\n# Run only API validation\nnpm run test:integration\n```\n\nAll remote authorization tests use a mock GitLab server and do not require actual GitLab credentials.\n",
  "bytes": 56497,
  "sha": "d067b4eba9c7d804b4e9d50de227dd207c42c96f6f330eb25bd71e7a25d0e867",
  "repo_slug": "zereight/gitlab-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://api.agentalog.com/api/listings/skl_zereight_gitlab_mcp_gitlab_mcp_skill_a61a37aa/readme"
}