gitlab-mcp-skill — Claude Code skill: setup

---
name: gitlab-mcp-skill
description: Use this skill when working with the GitLab MCP server tools for merge requests, issues, repositories, pipelines, work items, variables, dependency proxy, vulnerabilities, webhooks, search, CI catalog, and related GitLab workflows.
---

# gitlab-mcp

GitLab MCP server providing 278 tools: 275 tools across 24 toolsets, plus `execute_graphql`, the always-available `discover_tools` meta-tool, and `help`.

For exact generated parameter tables, see `docs/tools/`. Use this file for workflow shape and high-signal parameter hints.

## Toolsets

| Toolset | Default | Enable with |
|---|---|---|
| core (38 tools) | yes | default lean starter set |
| merge_requests (46 tools) | no | `GITLAB_TOOLSETS=merge_requests` |
| issues (24 tools) | no | `GITLAB_TOOLSETS=issues` |
| repositories (7 tools) | no | `GITLAB_TOOLSETS=repositories` |
| branches (16 tools) | no | `GITLAB_TOOLSETS=branches` |
| projects (11 tools) | no | `GITLAB_TOOLSETS=projects` |
| labels (5 tools) | no | `GITLAB_TOOLSETS=labels` |
| ci (4 tools) | no | `GITLAB_TOOLSETS=ci` |
| groups (1 tool) | no | `GITLAB_TOOLSETS=groups` |
| users (7 tools) | no | `GITLAB_TOOLSETS=users` |
| pipelines (58 tools) | no | `GITLAB_TOOLSETS=core,pipelines` (deprecated `USE_PIPELINE`; if `GITLAB_TOOLS` is unset, set `GITLAB_TOOLS=validate_ci_lint,validate_project_ci_lint`, otherwise append those tools instead of replacing the list) |
| milestones (17 tools) | no | `GITLAB_TOOLSETS=core,milestones` (deprecated `USE_MILESTONE`) |
| wiki (10 tools) | no | `GITLAB_TOOLSETS=core,wiki` (deprecated `USE_GITLAB_WIKI`) |
| releases (7 tools) | no | `GITLAB_TOOLSETS=releases` |
| tags (9 tools) | no | `GITLAB_TOOLSETS=tags` |
| snippets (5 tools) | no | `GITLAB_TOOLSETS=snippets` |
| workitems (18 tools) | no | `GITLAB_TOOLSETS=workitems` |
| webhooks (6 tools) | no | `GITLAB_TOOLSETS=webhooks` |
| search (3 tools) | no | `GITLAB_TOOLSETS=search` |
| variables (10 tools) | no | `GITLAB_TOOLSETS=variables` |
| dependency_proxy (4 tools) | no | `GITLAB_TOOLSETS=dependency_proxy` |
| vulnerabilities (4 tools) | no | `GITLAB_TOOLSETS=vulnerabilities` |
| orbit (4 tools) | no | `GITLAB_TOOLSETS=orbit` |
| api (1 tool) | no | `GITLAB_TOOLSETS=api` only (not `all`, not `discover_tools`, not `GITLAB_TOOLS`) |

Enable all discoverable toolsets: `GITLAB_TOOLSETS=all` (does **not** enable `api`). Restore the pre-lean default with `GITLAB_TOOLSETS=merge_requests,issues,repositories,branches,projects,labels,ci,groups,users`. Use `GITLAB_TOOLS` to enable individual tools outside their toolset, except explicit-only tools such as `gitlab_api_request`. `discover_tools` can list and activate opt-in categories for the current session, except `api`. `execute_graphql` is not in a toolset; enable it explicitly with `GITLAB_TOOLS=execute_graphql`. `USE_GITLAB_WIKI`, `USE_MILESTONE`, and `USE_PIPELINE` are deprecated (removed in next major (v3.0.0)). If you already set `GITLAB_TOOLSETS`, append the toolset to your existing list instead of replacing it. If `GITLAB_TOOLS` is unset, set `GITLAB_TOOLS=validate_ci_lint,validate_project_ci_lint`. If it is already set, append those two tools instead of replacing that list.

`gitlab_api_request` bypasses `GITLAB_ALLOWED_GROUPS` and other group restrictions, project allowlists, tool-level restrictions (`GITLAB_TOOLS`, `GITLAB_DENIED_TOOLS_REGEX` on other tools), and individual tool safety checks. The full token permission scope is exposed. Prompt injection can drive this tool. Operators who rely on these restrictions must NOT enable it. With `GITLAB_ALLOWED_PROJECT_IDS` or a session project scope, only `/projects/:id` paths for an allowed project are accepted; `/search`, `/users`, `/groups/:id`, `/runners`, and other paths are rejected. Body and query parameters that name another project are not checked. `GITLAB_PROJECT_ID` and OAuth group allowlists are not enforced.

The per-toolset counts above sum to 315 because the 38 `core` tools are each also listed
in their full category (`get_branch` and `list_branches` additionally appear in both
`merge_requests` and `branches`); the unique tool count across all toolsets is 275.

## Key Workflows

### Code Review (see reference/code-review.md)

1. `list_merge_request_changed_files` - get file paths only (no diffs)
2. `get_merge_request_file_diff` - get diffs for 3-5 files per call (batch)
3. `create_merge_request_thread` or `create_draft_note` - leave review comments
4. `bulk_publish_draft_notes` - publish all drafts at once

### MR Lifecycle (see reference/merge-requests.md)

`create_merge_request` -> review -> `approve_merge_request` -> `merge_merge_request`

### Issue Management (see reference/issues.md)

`create_issue` -> `create_issue_link` -> `create_issue_note` -> `update_issue`

Use `update_issue_description_patch` for small edits to long issue descriptions instead of resending the full body.

### Projects & Namespaces

- `get_project`, `list_projects`, `update_project` - inspect or change project settings
- `list_project_members`, `list_group_members` - search members by name or username within a project or group
- `list_namespaces`, `get_namespace`, `verify_namespace` - find target namespaces before creating projects/groups
- `verify_namespace.parent_id` scopes nested namespace checks
- `create_repository.namespace_id` creates a project under a group namespace

### Branches & Commits

- `create_branch`, `list_branches`, `get_branch`, `delete_branch`
- Protected branches: `list_protected_branches`, `get_protected_branch`, `protect_branch`, `update_protected_branch`, `unprotect_branch`, `update_default_branch` (`protect_branch` only creates a rule and returns 409 when one exists; change an existing rule with `update_protected_branch`, using record `id`s from `get_protected_branch`, instead of unprotect + protect)
- Commits: `list_commits`, `get_commit`, `get_commit_diff`, `get_file_blame`, `list_commit_statuses`, `create_commit_status`

### Tags

- `list_tags`, `get_tag`, `create_tag`, `delete_tag`, `get_tag_signature`
- Protected tags: `list_protected_tags`, `get_protected_tag`, `protect_tag`, `unprotect_tag` (`create_access_level` is 0, 30, or 40; wildcards such as `v*` are supported)

### CI

- Lint configs: `validate_ci_lint`, `validate_project_ci_lint`
- Catalog: `list_ci_catalog_resources`, `get_ci_catalog_resource`
- Pipelines/jobs/deployments: see reference/pipelines.md

### Work Items (see reference/work-items.md)

`list_work_items` -> `get_work_item` -> `update_work_item` -> `create_work_item_note`

### Variables & Dependency Proxy

Enable with `GITLAB_TOOLSETS=variables` or `GITLAB_TOOLSETS=dependency_proxy`.

- Variables: project/group CRUD tools (`list_*_variables`, `get_*_variable`, `create_*_variable`, `update_*_variable`, `delete_*_variable`)
- Dependency proxy: `get_dependency_proxy_settings`, `update_dependency_proxy_settings`, `list_dependency_proxy_blobs`, `purge_dependency_proxy_cache`

### Webhooks & Search

- Webhooks: see reference/webhooks.md
- Code search: see reference/search.md

### Vulnerability Triage (see reference/vulnerability-triage.md)

Enable with `GITLAB_TOOLSETS=vulnerabilities` (requires GitLab Ultimate).

`list_project_vulnerabilities` -> `get_vulnerability` -> `dismiss_vulnerability` or `confirm_vulnerability`

### File Operations

- Read: `get_file_contents`, `get_repository_tree`
- Write: `create_or_update_file` (single file), `push_files` (multiple files in one commit)

## Token-saving rules

- Do not dump a full `get_merge_request_diffs` payload into the conversation. List paths with `list_merge_request_changed_files`, then fetch 3–5 files per `get_merge_request_file_diff` call.
- Prefer a `jmespath` filter or `GITLAB_MCP_COMPACT_RESULTS` / `--compact-results` before asking the model to read a large JSON reply.
- Paginate `get_pipeline_job_output` with `limit` and `offset` instead of fetching an entire job log in one call.

## Parameter Hints

- **project_id**: numeric ID or URL-encoded path (`group%2Fsubgroup%2Fproject`)
- **namespace_id**: numeric namespace ID for `create_repository`; use `list_namespaces`/`verify_namespace` first
- **parent_id**: scope subgroup creation or `verify_namespace` for nested groups
- **MR lookup**: provide `merge_request_iid` or `source_branch`
- **list_issues**: default scope = created by current user. Use `scope: "all"` for all issues
- **list_merge_requests**: without project_id returns user's MRs across all projects
- **rebase_merge_request**: with `wait` true (default) returns the merge request plus `previous_sha` and `head_changed`
- **CI catalog resource lookup**: provide exactly one of `id` or `full_path`
- **emoji reactions**: merge request, issue, and work item reaction tools use GitLab emoji names like `thumbsup`, `rocket`, or `eyes`
- **work items**: status and custom fields require GitLab Premium/Ultimate features
- **execute_graphql**: escape double quotes in query strings

## Destructive Tools (require caution)

`cancel_pipeline`, `cancel_pipeline_job`, `delete_branch`, `delete_deployment`, `approve_deployment`, `delete_draft_note`, `delete_environment`, `erase_pipeline_job`, `delete_group_milestone`, `delete_group_variable`, `delete_group_wiki_page`, `delete_issue`, `delete_issue_emoji_reaction`, `delete_issue_link`, `delete_issue_note_emoji_reaction`, `delete_label`, `delete_merge_request_discussion_note`, `delete_merge_request_emoji_reaction`, `delete_merge_request_note`, `delete_merge_request_note_emoji_reaction`, `delete_milestone`, `delete_pipeline`, `delete_pipeline_schedule`, `delete_pipeline_schedule_variable`, `delete_pipeline_trigger`, `delete_project_variable`, `delete_release`, `delete_review_app_environments`, `delete_snippet`, `delete_tag`, `delete_webhook`, `delete_wiki_page`, `delete_work_item_emoji_reaction`, `delete_work_item_note_emoji_reaction`, `merge_merge_request`, `protect_branch`, `protect_tag`, `purge_dependency_proxy_cache`, `push_files`, `rebase_merge_request`, `stop_environment`, `stop_stale_environments`, `unprotect_branch`, `unprotect_tag`, `update_default_branch`, `update_protected_branch`, `gitlab_api_request`

## Advanced

- **Dynamic discovery**: `discover_tools` lists and activates opt-in toolsets at runtime. It cannot activate `api`
- **Workflow guide**: `help` returns on-demand guides (code-review, pipelines, issues, token-saving). Omit topic for the overview
- **Raw API**: `gitlab_api_request` only when `GITLAB_TOOLSETS` lists `api`. Readonly is GET-only; modify rejects DELETE
- **GraphQL**: `execute_graphql` for queries not covered by REST tools
- **Tool docs**: `docs/tools/` is generated from `tools/registry.ts`; prefer it for exact schemas
- **Remote MCP OAuth**: when `GITLAB_MCP_OAUTH=true`, `POST /register` (DCR) is rate-limited per client IP (default 20/hour via MCP SDK; tune with `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR`). Separate from `MAX_REQUESTS_PER_MINUTE` and GitLab API quotas — see [environment-variables.md](../../docs/configuration/environment-variables.md#oauth_register_rate_limit_per_hour)
- **Zoekt search**: `search_code`, `search_project_code`, `search_group_code` (requires advanced search enabled)
- **Work Items**: GraphQL-based alternative to issues (Premium/Ultimate features)