{"_id":"@alfonsodg/mcp-gitlab","_rev":"3-e1c7c4392402ade244a2148a6fbdd851","name":"@alfonsodg/mcp-gitlab","dist-tags":{"latest":"2.1.1"},"versions":{"2.0.25":{"name":"@alfonsodg/mcp-gitlab","version":"2.0.25","author":{"name":"zereight"},"license":"MIT","_id":"@alfonsodg/mcp-gitlab@2.0.25","maintainers":[{"name":"alfonsodg","email":"alfonsodg@gmail.com"}],"homepage":"https://github.com/zereight/gitlab-mcp#readme","bugs":{"url":"https://github.com/zereight/gitlab-mcp/issues"},"bin":{"mcp-gitlab":"build/index.js"},"dist":{"shasum":"77621af12afdec0e99d327e42255ca708ad7fa99","tarball":"https://registry.npmjs.org/@alfonsodg/mcp-gitlab/-/mcp-gitlab-2.0.25.tgz","fileCount":29,"integrity":"sha512-s/ufSpSZCj9zdzydgt/+iT48AmBPIKRmg/Q1x3dzoAVs2mpk6W0s9FHZXQMOUFJ7RzUNWV+ff+keqwRQjggP/w==","signatures":[{"sig":"MEYCIQCJzdzx08zP7Hi0NS9D5uzo5bgONbQBMLclT9i4IKkQGQIhAL94nChpuwF5avu91SaCu2JA4UKQ8vhleHROS+nkU9SP","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":567192},"type":"module","engines":{"npm":">=9.0.0","node":">=18.0.0"},"gitHead":"894dad97af4398700433c364bcbdcc5c7db99ec8","scripts":{"dev":"npm run build && node build/index.js","lint":"eslint . --ext .ts","test":"npm run test:all","build":"tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"","watch":"tsc --watch","deploy":"npm publish --access public","format":"prettier --write \"**/*.{js,ts,json,md}\"","prepare":"npm run build","lint:fix":"eslint . --ext .ts --fix","test:all":"npm run build && npm run test:mock && npm run test:live","changelog":"auto-changelog -p","test:live":"node test/validate-api.js","test:mock":"npx tsx --test test/remote-auth-simple-test.ts && tsx test/oauth-tests.ts && tsx test/test-list-merge-requests.ts && tsx test/test-list-project-members.ts","test:oauth":"tsx test/oauth-tests.ts","format:check":"prettier --check \"**/*.{js,ts,json,md}\"","test:approvals":"npm run build && tsx test/test-merge-request-approvals.ts","test:remote-auth":"npm run build && npx tsx --test test/remote-auth-simple-test.ts","test:list-merge-requests":"npm run build && tsx test/test-list-merge-requests.ts"},"_npmUser":{"name":"alfonsodg","email":"alfonsodg@gmail.com"},"repository":{"url":"git+https://github.com/zereight/gitlab-mcp.git","type":"git"},"_npmVersion":"10.9.3","description":"MCP server for using the GitLab API (with CLI args support)","directories":{},"_nodeVersion":"22.20.0","dependencies":{"zod":"^3.24.2","open":"^10.2.0","pino":"^9.7.0","express":"^5.1.0","form-data":"^4.0.0","node-fetch":"^3.3.2","pino-pretty":"^13.0.0","fetch-cookie":"^3.1.0","tough-cookie":"^5.1.2","pkce-challenge":"^5.0.0","http-proxy-agent":"^7.0.2","@types/node-fetch":"^2.6.12","https-proxy-agent":"^7.0.6","socks-proxy-agent":"^8.0.5","zod-to-json-schema":"3.24.5","@modelcontextprotocol/sdk":"^1.24.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.5","dotenv":"^17.2.2","eslint":"^9.18.0","ts-node":"^10.9.2","prettier":"^3.4.2","typescript":"^5.8.2","@types/node":"^22.13.10","@types/express":"^5.0.2","auto-changelog":"^2.4.0","@typescript-eslint/parser":"^8.21.0","@typescript-eslint/eslint-plugin":"^8.21.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-gitlab_2.0.25_1768935943989_0.04116202021938786","host":"s3://npm-registry-packages-npm-production"}},"2.0.26":{"name":"@alfonsodg/mcp-gitlab","version":"2.0.26","author":{"name":"zereight"},"license":"MIT","_id":"@alfonsodg/mcp-gitlab@2.0.26","maintainers":[{"name":"alfonsodg","email":"alfonsodg@gmail.com"}],"homepage":"https://github.com/zereight/gitlab-mcp#readme","bugs":{"url":"https://github.com/zereight/gitlab-mcp/issues"},"bin":{"mcp-gitlab":"build/index.js"},"dist":{"shasum":"b7edc4907e1aa81c10a4ad640d334fcee9582ce8","tarball":"https://registry.npmjs.org/@alfonsodg/mcp-gitlab/-/mcp-gitlab-2.0.26.tgz","fileCount":29,"integrity":"sha512-ok0mruALM6mI7IJx3XXIl2Bzq5kvPR5McgkDIaItaeyTkSmw5hTwVv/dSu7tRQxJZZYV5PWK0E9mvlXXo9pwJg==","signatures":[{"sig":"MEUCIB1ct9rU+srSTbUa2UUlZdIUa5Z059PwLNyMZ6YMHcMjAiEA1nvS3Suag49c+2T0hAcKNjswj3aEO0PXg1OYXbY62vY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":567209},"type":"module","engines":{"npm":">=9.0.0","node":">=18.0.0"},"gitHead":"f1570303964613182901a1bebe82b1c478daadbc","scripts":{"dev":"npm run build && node build/index.js","lint":"eslint . --ext .ts","test":"npm run test:all","build":"tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"","watch":"tsc --watch","deploy":"npm publish --access public","format":"prettier --write \"**/*.{js,ts,json,md}\"","prepare":"npm run build","lint:fix":"eslint . --ext .ts --fix","test:all":"npm run build && npm run test:mock && npm run test:live","changelog":"auto-changelog -p","test:live":"node test/validate-api.js","test:mock":"npx tsx --test test/remote-auth-simple-test.ts && tsx test/oauth-tests.ts && tsx test/test-list-merge-requests.ts && tsx test/test-list-project-members.ts","test:oauth":"tsx test/oauth-tests.ts","format:check":"prettier --check \"**/*.{js,ts,json,md}\"","test:approvals":"npm run build && tsx test/test-merge-request-approvals.ts","test:remote-auth":"npm run build && npx tsx --test test/remote-auth-simple-test.ts","test:list-merge-requests":"npm run build && tsx test/test-list-merge-requests.ts"},"_npmUser":{"name":"alfonsodg","email":"alfonsodg@gmail.com"},"repository":{"url":"git+https://github.com/zereight/gitlab-mcp.git","type":"git"},"_npmVersion":"10.9.3","description":"MCP server for using the GitLab API (with CLI args support)","directories":{},"_nodeVersion":"22.20.0","dependencies":{"zod":"^3.24.2","open":"^10.2.0","pino":"^9.7.0","tldts":"^6.1.86","express":"^5.1.0","form-data":"^4.0.0","node-fetch":"^3.3.2","pino-pretty":"^13.0.0","fetch-cookie":"^3.1.0","tough-cookie":"^5.1.2","pkce-challenge":"^5.0.0","http-proxy-agent":"^7.0.2","@types/node-fetch":"^2.6.12","https-proxy-agent":"^7.0.6","socks-proxy-agent":"^8.0.5","zod-to-json-schema":"3.24.5","@modelcontextprotocol/sdk":"^1.24.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.5","dotenv":"^17.2.2","eslint":"^9.18.0","ts-node":"^10.9.2","prettier":"^3.4.2","typescript":"^5.8.2","@types/node":"^22.13.10","@types/express":"^5.0.2","auto-changelog":"^2.4.0","@typescript-eslint/parser":"^8.21.0","@typescript-eslint/eslint-plugin":"^8.21.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-gitlab_2.0.26_1768936192944_0.21600398656582587","host":"s3://npm-registry-packages-npm-production"}},"2.1.1":{"name":"@alfonsodg/mcp-gitlab","version":"2.1.1","description":"GitLab MCP server for projects, merge requests, issues, pipelines, wiki, releases, and more","keywords":["gitlab","gitlab-mcp","mcp","mcp-server","model-context-protocol","gitlab-api","claude","cursor","vscode","copilot","ai-agent","merge-requests","pipelines","oauth","stdio","sse","streamable-http"],"license":"MIT","author":{"name":"zereight"},"type":"module","bin":{"mcp-gitlab":"build/index.js"},"repository":{"type":"git","url":"git+https://github.com/zereight/gitlab-mcp.git"},"publishConfig":{"access":"public"},"engines":{"node":">=18.0.0","npm":">=9.0.0"},"scripts":{"build":"tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"","prepare":"npm run build","dev":"npm run build && node build/index.js","watch":"tsc --watch","deploy":"npm publish --access public","changelog":"auto-changelog -p","test":"npm run test:all","test:all":"npm run build && npm run test:mock && npm run test:live","test:mock":"node --import tsx/esm --test test/remote-auth-simple-test.ts && node --import tsx/esm --test test/mcp-oauth-tests.ts && tsx test/oauth-tests.ts && tsx test/test-list-merge-requests.ts && tsx test/test-list-project-members.ts && tsx test/test-download-attachment.ts && node --import tsx/esm --test test/test-job-artifacts.ts && node --import tsx/esm --test test/test-deployment-tools.ts && node --import tsx/esm --test test/test-merge-request-approval-state-tools.ts && node --import tsx/esm --test test/test-search-code.ts && node --import tsx/esm --test test/test-toolset-filtering.ts && node --import tsx/esm --test test/test-auth-retry.ts","test:mcp-oauth":"npm run build && node --import tsx/esm --test test/mcp-oauth-tests.ts","test:live":"node test/validate-api.js","test:remote-auth":"npm run build && node --import tsx/esm --test test/remote-auth-simple-test.ts","test:schema":"tsx test/schema-tests.ts","test:oauth":"tsx test/oauth-tests.ts","test:list-merge-requests":"npm run build && tsx test/test-list-merge-requests.ts","test:approvals":"npm run build && tsx test/test-merge-request-approvals.ts","lint":"eslint . --ext .ts","lint:fix":"eslint . --ext .ts --fix","release":"bash scripts/release.sh","format":"prettier --write \"**/*.{js,ts,json,md}\"","format:check":"prettier --check \"**/*.{js,ts,json,md}\""},"dependencies":{"@modelcontextprotocol/sdk":"^1.24.2","@types/node-fetch":"^2.6.12","express":"^5.1.0","fetch-cookie":"^3.1.0","form-data":"^4.0.0","http-proxy-agent":"^7.0.2","https-proxy-agent":"^7.0.6","node-fetch":"^3.3.2","open":"^10.2.0","pino":"^9.7.0","pino-pretty":"^13.0.0","pkce-challenge":"^5.0.0","socks-proxy-agent":"^8.0.5","tldts":"^6.1.86","tough-cookie":"^5.1.2","zod":"^3.24.2","zod-to-json-schema":"3.24.5"},"devDependencies":{"@types/express":"^5.0.2","@types/node":"^22.13.10","@typescript-eslint/eslint-plugin":"^8.21.0","@typescript-eslint/parser":"^8.21.0","auto-changelog":"^2.4.0","dotenv":"^17.2.2","eslint":"^9.18.0","prettier":"^3.4.2","ts-node":"^10.9.2","tsx":"^4.20.5","typescript":"^5.8.2"},"gitHead":"a0e7d6d3aceb07c62821ebb932d2cad3c0db20c2","_id":"@alfonsodg/mcp-gitlab@2.1.1","bugs":{"url":"https://github.com/zereight/gitlab-mcp/issues"},"homepage":"https://github.com/zereight/gitlab-mcp#readme","_nodeVersion":"24.14.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-JiYG7MCX+BUDf++aahBozQCTr2YSzwdHeB0Ti5zsWrfvr0th/24RhdBY5hq+ey0aCGOpIv6ylHSFXTd1LDbE1Q==","shasum":"5f3a81b254b648a3c004b4b3edf2e7ef27eb783d","tarball":"https://registry.npmjs.org/@alfonsodg/mcp-gitlab/-/mcp-gitlab-2.1.1.tgz","fileCount":52,"unpackedSize":989287,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCID71mTdZTlTSxfMif2FF4u/BPiWV6hJoSZ2t+j+70AwpAiEAptOp3/ahiLYE+izfCSjMd/4Vr9Ip2FfaVISeSsvCfEQ="}]},"_npmUser":{"name":"alfonsodg","email":"alfonsodg@gmail.com"},"directories":{},"maintainers":[{"name":"alfonsodg","email":"alfonsodg@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-gitlab_2.1.1_1776523927275_0.03931458301883417"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-20T19:05:43.794Z","modified":"2026-04-18T14:52:07.588Z","2.0.25":"2026-01-20T19:05:44.197Z","2.0.26":"2026-01-20T19:09:53.079Z","2.1.1":"2026-04-18T14:52:07.489Z"},"bugs":{"url":"https://github.com/zereight/gitlab-mcp/issues"},"author":{"name":"zereight"},"license":"MIT","homepage":"https://github.com/zereight/gitlab-mcp#readme","repository":{"type":"git","url":"git+https://github.com/zereight/gitlab-mcp.git"},"description":"GitLab MCP server for projects, merge requests, issues, pipelines, wiki, releases, and more","maintainers":[{"name":"alfonsodg","email":"alfonsodg@gmail.com"}],"readme":"# GitLab MCP Server\n\n> **New Feature**: Dynamic GitLab API URL support with connection pooling! See [Dynamic API URL Documentation](docs/dynamic-api-url.md) for details.\n\n[![Star History Chart](https://api.star-history.com/svg?repos=zereight/gitlab-mcp&type=Date)](https://www.star-history.com/#zereight/gitlab-mcp&Date)\n\n## @zereight/mcp-gitlab\n\nA comprehensive GitLab MCP server for AI clients. Manage projects, merge requests, issues, pipelines, wiki, releases, 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- Broad GitLab coverage — projects, repository browsing, merge requests, issues, pipelines, wiki, releases, labels, milestones, and more\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\nQuick start: choose either Personal Access Token or OAuth2 setup below and use `@zereight/mcp-gitlab` in your MCP client configuration.\n\n### Client Setup Guides\n\n- [Claude Code Setup Guide](./docs/claude-code-setup.md)\n- [VS Code Setup Guide](./docs/vscode-setup.md)\n- [GitHub Copilot Setup Guide](./docs/copilot-setup.md)\n- [Codex Setup Guide](./docs/codex-setup.md)\n- [Cursor Setup Guide](./docs/cursor-setup.md)\n- [JSON-Based MCP Clients Setup Guide](./docs/json-mcp-clients-setup.md) - for Factory AI Droid, OpenClaw, and OpenCode style clients\n- [OAuth2 Authentication Setup Guide](./docs/oauth-setup.md)\n- [Environment Variables Reference](./docs/environment-variables.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/claude-code-setup.md)\n- **VS Code**: see [VS Code Setup Guide](./docs/vscode-setup.md)\n- **GitHub Copilot**: see [GitHub Copilot Setup Guide](./docs/copilot-setup.md)\n- **Codex**: see [Codex Setup Guide](./docs/codex-setup.md)\n- **Cursor**: see [Cursor Setup Guide](./docs/cursor-setup.md)\n- **Factory AI Droid / OpenClaw / OpenCode style clients**: see [JSON-Based MCP Clients Setup Guide](./docs/json-mcp-clients-setup.md)\n- **OAuth browser flow details**: see [OAuth2 Authentication Setup Guide](./docs/oauth-setup.md)\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\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\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@zereight/mcp-gitlab\",\n        \"--token=YOUR_GITLAB_TOKEN\",\n        \"--api-url=https://gitlab.com/api/v4\"\n      ],\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`)\n- `--use-wiki=true` - Enable wiki API (replaces `USE_GITLAB_WIKI`)\n- `--use-milestone=true` - Enable milestone API (replaces `USE_MILESTONE`)\n- `--use-pipeline=true` - Enable pipeline API (replaces `USE_PIPELINE`)\n\nCLI arguments take precedence over environment variables.\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_READ_ONLY_MODE=true \\\n  -e USE_GITLAB_WIKI=true \\\n  -e USE_MILESTONE=true \\\n  -e USE_PIPELINE=true \\\n  -e SSE=true \\\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    }\n  }\n}\n```\n\n- streamable-http\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_READ_ONLY_MODE=true \\\n  -e USE_GITLAB_WIKI=true \\\n  -e USE_MILESTONE=true \\\n  -e USE_PIPELINE=true \\\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    }\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\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_SCOPES` | optional | Comma-separated scopes (default: `api,read_api,read_user`) |\n\n```shell\ndocker run -i --rm \\\n  -e HOST=0.0.0.0 \\\n  -e GITLAB_MCP_OAUTH=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\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/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`, `HOST`, `PORT`\n\nCommonly referenced variables:\n\n- `GITLAB_API_URL`\n- `GITLAB_PERSONAL_ACCESS_TOKEN`\n- `GITLAB_USE_OAUTH`\n- `REMOTE_AUTHORIZATION`\n- `GITLAB_MCP_OAUTH`\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\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_READ_ONLY_MODE=true \\\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:** Each session is limited to `MAX_REQUESTS_PER_MINUTE` requests per minute (default 60)\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                                                                                                                                                                                 |\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| `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- **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, and pipelines\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 in a GitLab project\n2. `create_or_update_file` - Create or update a single file in a GitLab project\n3. `search_repositories` - Search for GitLab projects\n4. `create_repository` - Create a new GitLab project\n5. `get_file_contents` - Get the contents of a file or directory from a GitLab project\n6. `push_files` - Push multiple files to a GitLab project in a single commit\n7. `create_issue` - Create a new issue in a GitLab project\n8. `create_merge_request` - Create a new merge request in a GitLab project\n9. `fork_repository` - Fork a GitLab project to your account or specified namespace\n10. `create_branch` - Create a new branch in a GitLab project\n11. `get_merge_request` - Get details of a merge request with compact deployment summary, behind-count, commit addition summary, and approval summary (Either mergeRequestIid or branchName must be provided)\n12. `get_merge_request_diffs` - Get the changes/diffs of a merge request (Either mergeRequestIid or branchName must be provided)\n13. `list_merge_request_diffs` - List merge request diffs with pagination support (Either mergeRequestIid or branchName must be provided)\n14. `get_merge_request_conflicts` - Get the conflicts of a merge request in a GitLab project\n15. `list_merge_request_changed_files` - STEP 1 of code review workflow. Returns ONLY the list of changed file paths in a merge request — WITHOUT diff content. Call this first to get file paths, then call get_merge_request_file_diff with multiple files in a single batched call (recommended 3-5 files per call). Supports excluded_file_patterns filtering using regex. (Either mergeRequestIid or branchName must be provided)\n16. `get_merge_request_file_diff` - STEP 2 of code review workflow. Get diffs for one or more files from a merge request. Call list_merge_request_changed_files first, then pass them as an array to fetch diffs efficiently. Batching multiple files (recommended 3-5) is supported. (Either mergeRequestIid or branchName must be provided)\n17. `list_merge_request_versions` - List all versions of a merge request\n18. `get_merge_request_version` - Get a specific version of a merge request\n19. `get_branch_diffs` - Get the changes/diffs between two branches or commits in a GitLab project\n20. `update_merge_request` - Update a merge request (Either mergeRequestIid or branchName must be provided)\n21. `create_note` - Create a new note (comment) to an issue or merge request\n22. `create_merge_request_thread` - Create a new thread on a merge request\n23. `mr_discussions` - List discussion items for a merge request\n24. `resolve_merge_request_thread` - Resolve a thread on a merge request\n25. `update_merge_request_note` - Modify an existing merge request thread note\n26. `create_merge_request_note` - Add a new note to an existing merge request thread\n27. `delete_merge_request_discussion_note` - Delete a discussion note on a merge request\n28. `update_merge_request_discussion_note` - Update a discussion note on a merge request\n29. `create_merge_request_discussion_note` - Add a new discussion note to an existing merge request thread\n30. `delete_merge_request_note` - Delete an existing merge request note\n31. `get_merge_request_note` - Get a specific note for a merge request\n32. `get_merge_request_notes` - List notes for a merge request\n33. `get_draft_note` - Get a single draft note from a merge request\n34. `list_draft_notes` - List draft notes for a merge request\n35. `create_draft_note` - Create a draft note for a merge request\n36. `update_draft_note` - Update an existing draft note\n37. `delete_draft_note` - Delete a draft note\n38. `publish_draft_note` - Publish a single draft note\n39. `bulk_publish_draft_notes` - Publish all draft notes for a merge request\n40. `list_merge_requests` - List merge requests globally or in a specific GitLab project with filtering options (project_id is now optional)\n41. `approve_merge_request` - Approve a merge request (requires appropriate permissions)\n42. `unapprove_merge_request` - Unapprove a previously approved merge request\n43. `get_merge_request_approval_state` - Get merge request approval details including approvers (uses `approval_state` when available, otherwise falls back to `approvals`)\n44. `update_issue_note` - Modify an existing issue thread note\n45. `create_issue_note` - Add a new note to an existing issue thread\n46. `list_issues` - List issues (default: created by current user only; use scope='all' for all accessible issues)\n47. `my_issues` - List issues assigned to the authenticated user (defaults to open issues)\n48. `get_issue` - Get details of a specific issue in a GitLab project\n49. `update_issue` - Update an issue in a GitLab project\n50. `delete_issue` - Delete an issue from a GitLab project\n51. `list_issue_links` - List all issue links for a specific issue\n52. `list_issue_discussions` - List discussions for an issue in a GitLab project\n53. `get_issue_link` - Get a specific issue link\n54. `create_issue_link` - Create an issue link between two issues\n55. `delete_issue_link` - Delete an issue link\n56. `list_namespaces` - List all namespaces available to the current user\n57. `get_namespace` - Get details of a namespace by ID or path\n58. `verify_namespace` - Verify if a namespace path exists\n59. `get_project` - Get details of a specific project\n60. `list_projects` - List projects accessible by the current user\n61. `list_project_members` - List members of a GitLab project\n62. `list_group_projects` - List projects in a GitLab group with filtering options\n63. `list_group_iterations` - List group iterations with filtering options\n64. `list_labels` - List labels for a project\n65. `get_label` - Get a single label from a project\n66. `create_label` - Create a new label in a project\n67. `update_label` - Update an existing label in a project\n68. `delete_label` - Delete a label from a project\n69. `list_pipelines` - List pipelines in a GitLab project with filtering options\n70. `get_pipeline` - Get details of a specific pipeline in a GitLab project\n71. `list_pipeline_jobs` - List all jobs in a specific pipeline\n72. `list_pipeline_trigger_jobs` - List all trigger jobs (bridges) in a specific pipeline that trigger downstream pipelines\n73. `get_pipeline_job` - Get details of a GitLab pipeline job number\n74. `get_pipeline_job_output` - Get the output/trace of a GitLab pipeline job with optional pagination to limit context window usage\n75. `create_pipeline` - Create a new pipeline for a branch or tag\n76. `retry_pipeline` - Retry a failed or canceled pipeline\n77. `cancel_pipeline` - Cancel a running pipeline\n78. `play_pipeline_job` - Run a manual pipeline job\n79. `retry_pipeline_job` - Retry a failed or canceled pipeline job\n80. `cancel_pipeline_job` - Cancel a running pipeline job\n81. `list_deployments` - List deployments in a GitLab project with filtering options\n82. `get_deployment` - Get details of a specific deployment in a GitLab project\n83. `list_environments` - List environments in a GitLab project\n84. `get_environment` - Get details of a specific environment in a GitLab project\n85. `list_job_artifacts` - List artifact files in a job's artifacts archive. Returns file names, paths, types, and sizes\n86. `download_job_artifacts` - Download the entire artifact archive (zip) for a job to a local path. Returns the saved file path\n87. `get_job_artifact_file` - Get the content of a single file from a job's artifacts by its path within the archive\n88. `list_milestones` - List milestones in a GitLab project with filtering options\n89. `get_milestone` - Get details of a specific milestone\n90. `create_milestone` - Create a new milestone in a GitLab project\n91. `edit_milestone` - Edit an existing milestone in a GitLab project\n92. `delete_milestone` - Delete a milestone from a GitLab project\n93. `get_milestone_issue` - Get issues associated with a specific milestone\n94. `get_milestone_merge_requests` - Get merge requests associated with a specific milestone\n95. `promote_milestone` - Promote a milestone to the next stage\n96. `get_milestone_burndown_events` - Get burndown events for a specific milestone\n97. `list_wiki_pages` - List wiki pages in a GitLab project\n98. `get_wiki_page` - Get details of a specific wiki page\n99. `create_wiki_page` - Create a new wiki page in a GitLab project\n100. `update_wiki_page` - Update an existing wiki page in a GitLab project\n101. `delete_wiki_page` - Delete a wiki page from a GitLab project\n102. `list_group_wiki_pages` - List wiki pages in a GitLab group\n103. `get_group_wiki_page` - Get details of a specific group wiki page\n104. `create_group_wiki_page` - Create a new wiki page in a GitLab group\n105. `update_group_wiki_page` - Update an existing wiki page in a GitLab group\n106. `delete_group_wiki_page` - Delete a wiki page from a GitLab group\n107. `get_repository_tree` - Get the repository tree for a GitLab project (list files and directories)\n108. `list_commits` - List repository commits with filtering options\n109. `get_commit` - Get details of a specific commit\n110. `get_commit_diff` - Get changes/diffs of a specific commit\n111. `list_releases` - List all releases for a project\n112. `get_release` - Get a release by tag name\n113. `create_release` - Create a new release in a GitLab project\n114. `update_release` - Update an existing release in a GitLab project\n115. `delete_release` - Delete a release from a GitLab project (does not delete the associated tag)\n116. `create_release_evidence` - Create release evidence for an existing release (GitLab Premium/Ultimate only)\n117. `download_release_asset` - Download a release asset file by direct asset path\n118. `get_users` - Get GitLab user details by usernames\n119. `list_events` - List all events for the currently authenticated user\n120. `get_project_events` - List all visible events for a specified project\n121. `upload_markdown` - Upload a file to a GitLab project for use in markdown content\n122. `download_attachment` - Download an uploaded file from a GitLab project by secret and filename\n123. `get_work_item` - Get a single work item with full details including status, hierarchy (parent/children), type, labels, assignees, and all widgets\n124. `list_work_items` - List work items in a project with filters (type, state, search, assignees, labels). Returns items with status and hierarchy info\n125. `create_work_item` - Create a new work item (issue, task, incident, test_case, epic, key_result, objective, requirement, ticket). Supports setting title, description, labels, assignees, weight, parent, health status, start/due dates, milestone, and confidentiality\n126. `update_work_item` - Update a work item. Can modify title, description, labels, assignees, weight, state, status, parent hierarchy, children, health status, start/due dates, milestone, confidentiality, linked items, and custom fields\n127. `convert_work_item_type` - Convert a work item to a different type (e.g. issue to task, task to incident)\n128. `list_work_item_statuses` - List available statuses for a work item type in a project. Requires GitLab Premium/Ultimate with configurable statuses\n129. `list_custom_field_definitions` - List available custom field definitions for a work item type in a project. Returns field names, types, and IDs needed for setting custom fields via update_work_item\n130. `move_work_item` - Move a work item (issue, task, etc.) to a different project. Uses GitLab GraphQL issueMove mutation\n131. `list_work_item_notes` - List notes and discussions on a work item. Returns threaded discussions with author, body, timestamps, and system/internal flags\n132. `create_work_item_note` - Add a note/comment to a work item. Supports Markdown, internal notes, and threaded replies\n133. `get_timeline_events` - List timeline events for an incident. Returns chronological events with notes, timestamps, and tags\n134. `create_timeline_event` - Create a timeline event on an incident. Supports tags: 'Start time', 'End time', 'Impact detected', 'Response initiated', 'Impact mitigated', 'Cause identified'\n135. `list_webhooks` - List all configured webhooks for a GitLab project or group. Provide either project_id or group_id\n136. `list_webhook_events` - List recent webhook events (past 7 days) for a project or group webhook. Use summary mode for overview, then get_webhook_event for full details\n137. `get_webhook_event` - Get full details of a specific webhook event by ID, including request/response payloads\n138. `search_code` - Search for code across all projects on the GitLab instance (requires advanced search or exact code search to be enabled)\n139. `search_project_code` - Search for code within a specific GitLab project (requires advanced search or exact code search to be enabled)\n140. `search_group_code` - Search for code within a specific GitLab group (requires advanced search or exact code search to be enabled)\n141. `execute_graphql` - Execute a GitLab GraphQL query\n<!-- TOOLS-END -->\n\n</details>\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","readmeFilename":"README.md","keywords":["gitlab","gitlab-mcp","mcp","mcp-server","model-context-protocol","gitlab-api","claude","cursor","vscode","copilot","ai-agent","merge-requests","pipelines","oauth","stdio","sse","streamable-http"]}