v2.3.4

Changes in v2.3.4

✨ Features

• feat: add static MCP resources catalog (follow-up to #695) #842
• feat: add title and website URL to the registry and server metadata #858

🐛 Bug Fixes

• fix(security): harden startup URL redaction edge cases (#826) #841
• fix: name the reason when a tool call cannot reach GitLab #856
• fix: report a poll still in flight at the deadline as a timeout #869
• fix(server): raise HTTP request body limit #871
• fix: drop non-object structuredContent after a jmespath filter #873

⚡ Performance

• perf: return compact JSON from the remaining pretty-printed tools #857

📝 Documentation

• docs(readme): serve stars, downloads and license badges from badgen.net #868

🔨 Chore

• chore: add CODEOWNERS and document the weekly release process #870

Contributors

• @zereight (9 PRs: #841, #842, #856, #857, #858, #868, #869, #870, #873)
• @bufferoverflow (1 PR: #871)

⚠️ Deprecation notice

Deprecated configuration options (e.g. GITLAB_READ_ONLY_MODE, USE_GITLAB_WIKI, and other legacy flags) still work during the grace period, but they will be removed in v3.0.0. Please migrate to the replacements described in the pinned issue #815.

v2.3.3

Changes in v2.3.3

🐛 Bug Fixes

• fix(merge-requests): re-check head before reporting an unchanged rebase (#864) #866

Contributors

• @zereight (1 PR: #866)

⚠️ Deprecation notice

Deprecated configuration options (e.g. GITLAB_READ_ONLY_MODE, USE_GITLAB_WIKI, and other legacy flags) still work during the grace period, but they will be removed in v3.0.0. Please migrate to the replacements described in the pinned issue #815.

v2.3.2

Changes in v2.3.2

✨ Features

• feat(registry): publish Docker image as OCI package in server.json #859
• feat(mcpb): ship a Claude Desktop MCP Bundle with each release #860
• feat: return argument validation errors as isError tool results #861
• feat: report whether rebase_merge_request moved the head #862

⬆️ Upgrade notes

• #861: Tool argument validation failures are now returned as a tool result with isError: true (with the validation message) instead of a JSON-RPC -32603 error. If your client or scripts relied on the -32603 error for invalid arguments, check isError on the tool result instead.

Contributors

• @zereight (3 PRs: #859, #860, #861)
• @ALERTua (1 PR: #862)

⚠️ Deprecation notice

Deprecated configuration options (e.g. GITLAB_READ_ONLY_MODE, USE_GITLAB_WIKI, and other legacy flags) still work during the grace period, but they will be removed in v3.0.0 (grace period ends 2026-11-09). Please migrate to the replacements described in the pinned issue #815.

v2.3.1

Changes in v2.3.1

🐛 Bug Fixes

• fix(schemas): parse "false" as false in tool boolean arguments #848

⬆️ Upgrade notes (behavior change)

• Boolean tool arguments now parse the string "false" as false. Previously any non-empty string, including "false", was coerced to true.
• Other non-boolean strings such as "" or "yes" are now rejected with a validation error instead of being treated as true. Send real booleans (true/false) or the strings "true"/"false".

Contributors

• @zereight (1 PR: #848)

⚠️ Deprecation notice

Deprecated configuration options (e.g. GITLAB_READ_ONLY_MODE, USE_GITLAB_WIKI, and other legacy flags) still work during the grace period, but they will be removed in v3.0.0. Please migrate to the replacements described in the pinned issue #815.

v2.3.0

⚠️ Upgrade notes

This release fixes seven security advisories (see Security below). Four of the fixes change behavior for some setups:

1. Callback proxy mode: client callback allowlist and consent page (GHSA-5w3p-qj7g-79v5)

With GITLAB_MCP_OAUTH=true and GITLAB_OAUTH_CALLBACK_PROXY=true:

• /authorize now shows a consent page with the client name and the callback host. Users approve once per client and callback URL (remembered for 30 days; without OAUTH_STATELESS_MODE=true the signing key is per process, so users are asked again after a restart).
• Client callbacks must be listed in GITLAB_OAUTH_ALLOWED_REDIRECT_URIS. The default covers Claude, ChatGPT, Cursor and loopback callbacks. Other clients fail registration with invalid_redirect_uri (the server log names the refused URL). Add them with GITLAB_OAUTH_ALLOWED_REDIRECT_URIS=defaults,https://mcp.example.com/oauth/callback. * turns the allowlist off (not recommended).

2. download_attachment saves under GITLAB_DOWNLOAD_DIR (GHSA-vhp9-2xfv-rrfv)

In stdio mode:

• Files are saved under GITLAB_DOWNLOAD_DIR (default .gitlab-mcp-downloads in the working directory, created with a .gitignore). local_path is now a subdirectory of that directory, not of the working directory.
• Existing files are never replaced, and local_path segments or filenames starting with a dot (.git, .vscode, .envrc) are rejected.
• In readonly mode (GITLAB_PERMISSION_MODE=readonly or GITLAB_READ_ONLY_MODE=true) no files are written: download_attachment only returns images inline, and download_job_artifacts is rejected.

3. Local OAuth: shared callback server needs a key and a loopback host (GHSA-64g9-hrwx-9g6m)

With GITLAB_USE_OAUTH=true, stdio sessions can share one OAuth callback port only when they run as the same OS user with the same home directory (the key is in ~/.gitlab-mcp-oauth-<port>.key) and all run this release or later. Restart all sessions after upgrading. The callback server only answers requests addressed to 127.0.0.1, localhost, [::1], or the host in GITLAB_OAUTH_REDIRECT_URI.

4. GITLAB_OAUTH_ALLOWED_GROUPS is enforced on every request (GHSA-2jv7-p2g4-9f2h)

The group check used to run only at OAuth code exchange. It now also runs on every /mcp request and on token refresh:

• JOB-TOKEN header auth gets 403 while allowed groups are set (a CI job token cannot list the user's groups). Use OAuth or a Private-Token header from CI.
• Private-Token headers, OAuth Bearer tokens (including tokens from other GitLab OAuth apps) and stateless session ids of users outside the allowed groups get 403.
• Token refresh is re-checked and fails with invalid_grant for non-members.
• Results are cached per token for 5 minutes per process, so removing a user takes effect within 5 minutes.

Also: tools listed in GITLAB_TOOL_POLICY_HIDDEN are now callable only when their toolset (or GITLAB_TOOLS) enables them (GHSA-3gfg-wh5g-cf74). If you relied on hiding a tool to make it callable, enable it explicitly.

---

Changes in v2.3.0

🔐 Security

• fix(oauth): check client callbacks and ask for consent in callback proxy mode (GHSA-5w3p-qj7g-79v5, high). With GITLAB_OAUTH_CALLBACK_PROXY=true, a client registered with any redirect_uri could receive another user's authorization and redeem it for their GitLab tokens.
• fix(download): save attachments as new files under a download directory (GHSA-vhp9-2xfv-rrfv, high). In stdio mode download_attachment could create or overwrite any file under the working directory, including .git and editor config, also in readonly mode.
• fix(scope): check target projects and work item notes against the allowlist (GHSA-ffr3-5f57-gf93, medium). With GITLAB_ALLOWED_PROJECT_IDS set, create_issue_link and create_merge_request did not check target_project_id, and the work item note emoji tools acted on any note.
• fix(oauth): require a key and a loopback host on the shared callback server (GHSA-64g9-hrwx-9g6m, medium). With GITLAB_USE_OAUTH=true, the shared local callback server returned new tokens to any caller of /auth-request.
• fix(tools): keep hidden-policy tools inside the enabled toolsets (GHSA-3gfg-wh5g-cf74, medium). GITLAB_TOOL_POLICY_HIDDEN made tools callable even when their toolset was off, including gitlab_api_request and execute_graphql.
• fix(oauth): enforce allowed groups on every request and refresh (GHSA-2jv7-p2g4-9f2h, medium). GITLAB_OAUTH_ALLOWED_GROUPS was only checked when an OAuth code was exchanged.
• fix(http): redact session ids in logs and bind OAuth sessions to their user (GHSA-g4cw-m236-q72h, low). Full session ids were logged, and another user's token could use an MCP OAuth session.

All users should upgrade.

✨ Features

• feat: add rebase_merge_request tool #844

📝 Documentation

• docs(docker): make Docker quick starts start on first run #849

🔬 CI/Test

• ci: make lint and format checks pass so they can be enforced #850
• test: run the excluded mock suites in test:mock #851

🔨 Chore

• chore(release): regenerate server-card and auto-add v3 deprecation notice #846
• chore(tools): shorten generic sentences in tool descriptions #852

Contributors

• @zereight (5 PRs: #846, #849, #850, #851, #852)
• @ALERTua (1 PR: #844)

⚠️ Deprecation notice

Deprecated configuration options (e.g. GITLAB_READ_ONLY_MODE, USE_GITLAB_WIKI, and other legacy flags) still work during the grace period, but they will be removed in v3.0.0. Please migrate to the replacements described in the pinned issue #815.

v2.2.6

Changes in v2.2.6

🔐 Security

• fix(auth): bind dynamic project scope to the session (GHSA-qcj2-qcc2-5fg4). With REMOTE_AUTHORIZATION=true and ENABLE_DYNAMIC_PROJECT_SCOPE=true, the X-GitLab-Allowed-Project-Ids scope established at session initialization is now enforced for the whole session: omitting the header keeps the session scope, and a different scope is rejected with 401. Re-initialize the session to change scope. All users of dynamic project scoping should upgrade.

📝 Documentation

• docs: sync server-card version with package.json (2.2.5) #845

Contributors

• @zereight (1 PR: #845)

⚠️ Deprecation notice

Deprecated configuration options (e.g. GITLAB_READ_ONLY_MODE, USE_GITLAB_WIKI, and other legacy flags) still work during the grace period, but they will be removed in v3.0.0. Please migrate to the replacements described in the pinned issue #815.

v2.2.5

Changes in v2.2.5

✨ Features

• feat: add explicit opt-in gitlab_api_request tool (#804) #813

Contributors

• @zereight (1 PR: #813)

🔐 Security note: gitlab_api_request

The new gitlab_api_request tool is off by default. It is enabled only when you explicitly list api in GITLAB_TOOLSETS (e.g. GITLAB_TOOLSETS=core,api); GITLAB_TOOLSETS=all, discover_tools, and GITLAB_TOOLS do not enable it. Once enabled, it can call arbitrary GitLab REST APIs with your token, bypassing the safeguards of the dedicated tools. Only enable it when you actually need it, and combine it with read-only mode (GITLAB_PERMISSION_MODE=readonly, which allows GET only) and GITLAB_ALLOWED_PROJECT_IDS (enforced for /projects/:id paths). See docs/tools/api.md.

⚠️ Deprecation notice

Deprecated configuration options (e.g. GITLAB_READ_ONLY_MODE, USE_GITLAB_WIKI, and other legacy flags) still work during the grace period, but they will be removed in v3.0.0. Please migrate to the replacements described in the pinned issue #815.

v2.2.4

Changes in v2.2.4

✨ Features

• feat: add GITLAB_PERSONAL_ACCESS_TOKEN_FILE #839

📝 Documentation

• docs: keep PAT out of shell history in install examples #837

🔬 CI/Test

• ci: raise docker-publish timeout to 40 minutes #836

🔨 Chore

• chore: regenerate server-card.json for 2.2.3 #838

Contributors

• @zereight (4 PRs: #836, #837, #838, #839)

⚠️ Deprecation notice

Deprecated configuration options (e.g. GITLAB_READ_ONLY_MODE, USE_GITLAB_WIKI, and other legacy flags) still work during the grace period, but they will be removed in v3.0.0. Please migrate to the replacements described in the pinned issue #815.

v2.2.3

Changes in v2.2.3

🐛 Bug Fixes

• fix(registry): drop deprecated env vars from server.json, add GITLAB_PERMISSION_MODE #830

📝 Documentation

• docs: fix broken README badges and install buttons (DeepWiki, VS Code, add Cursor) #829
• docs: add SECURITY.md, issue templates, and PR template #831
• docs(readme): compare with GitLab official MCP server and add quick setup table #832

Contributors

• @zereight (4 PRs: #829, #830, #831, #832)

⚠️ Deprecation notice

Deprecated configuration options (e.g. GITLAB_READ_ONLY_MODE, USE_GITLAB_WIKI, and other legacy flags) still work during the grace period, but they will be removed in v3.0.0. Please migrate to the replacements described in the pinned issue #815.

v2.2.2

Changes in v2.2.2

✨ Features

• feat(smithery): add gitlabPermissionMode config option #820
• feat: add read-only project runner tools #822

🐛 Bug Fixes

• fix(health_check): return network/TLS failures as structured result #811
• fix: emit deprecated env warnings earlier and on CLI/auth paths #816
• fix: return project allowlist denials as isError tool results #817
• fix: redact credentials in startup URL logs #823
• fix(health_check): catch transport errors from the job-token fallback #827

📝 Documentation

• docs: include core in deprecated env replacements and mark deprecated settings #814
• docs(test): align test README with real scripts; accept /api/v4 in test:live URL #818
• docs: align mkdocs nav label for GitLab Orbit #824

🔨 Chore

• chore(deps-dev): bump handlebars from 4.7.9 to 4.7.10 in the npm_and_yarn group across 1 directory #809
• chore: regenerate server-card.json #825

Other Changes

• Add protected tag tools #821

Contributors

• @zereight (12 PRs: #811, #814, #816, #817, #818, #820, #821, #822, #823, #824, #825, #827)
• @dependabot[bot] (1 PR: #809)