gitlab-mcp

GitLab MCP server providing 288 tools: 285 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

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 325 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 285.

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.

Board order: reorder_issue with move_after_id / move_before_id (the neighbor issue's global id, not its iid).

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
• list_group_iterations, get_group_iteration, update_group_iteration, create_group_iteration, delete_group_iteration - list, fetch, update, create, or delete a group iteration
• list_project_iterations - list iterations available to a project
• list_group_iteration_cadences, create_group_iteration_cadence, update_group_iteration_cadence, delete_group_iteration_cadence - manage iteration cadences
• update_work_item.remove_iteration detaches a work item from its iteration
• 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 ids 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_iteration, delete_group_iteration_cadence, 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
• Zoekt search: search_code, search_project_code, search_group_code (requires advanced search enabled)
• Work Items: GraphQL-based alternative to issues (Premium/Ultimate features)