gitlab-mcp-skill

# gitlab-mcp

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

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 (15 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. `GITLAB_ALLOWED_PROJECT_IDS` is checked only for `/projects/:id` paths; `/search`, `/users`, `/groups/:id`, and `/runners` are not constrained. `GITLAB_PROJECT_ID` and OAuth group allowlists are not enforced.

The per-toolset counts above sum to 314 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 274.

## 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`, `unprotect_branch`, `update_default_branch`
- 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)

## 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`, `gitlab_api_request`

## Advanced

- **Dynamic discovery**: `discover_tools` lists and activates opt-in toolsets at runtime. It cannot activate `api`
- **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)

Shown under the source repo’s MIT license. Read the full folder on GitHub.