gitlab-mcp-skill

gitlab-mcp

GitLab MCP 服务提供 278 个工具：涵盖 24 个工具集的 275 个工具，另加 execute_graphql、始终可用的元工具 discover_tools，以及 help。

如需查看精确生成的参数表，请参阅 docs/tools/。本文档介绍工作流结构，并提示重要参数。

工具集

工具集	默认启用	启用方式
core（38 个工具）	是	默认的精简入门集合
merge_requests（46 个工具）	否	GITLAB_TOOLSETS=merge_requests
issues（24 个工具）	否	GITLAB_TOOLSETS=issues
repositories（7 个工具）	否	GITLAB_TOOLSETS=repositories
branches（16 个工具）	否	GITLAB_TOOLSETS=branches
projects（11 个工具）	否	GITLAB_TOOLSETS=projects
labels（5 个工具）	否	GITLAB_TOOLSETS=labels
ci（4 个工具）	否	GITLAB_TOOLSETS=ci
groups（1 个工具）	否	GITLAB_TOOLSETS=groups
users（7 个工具）	否	GITLAB_TOOLSETS=users
pipelines（58 个工具）	否	GITLAB_TOOLSETS=core,pipelines（已弃用 USE_PIPELINE；如果未设置 GITLAB_TOOLS，请设置 GITLAB_TOOLS=validate_ci_lint,validate_project_ci_lint；否则将这些工具追加到列表中，而不是替换列表）
milestones（17 个工具）	否	GITLAB_TOOLSETS=core,milestones（已弃用 USE_MILESTONE）
wiki（10 个工具）	否	GITLAB_TOOLSETS=core,wiki（已弃用 USE_GITLAB_WIKI）
releases（7 个工具）	否	GITLAB_TOOLSETS=releases
tags（9 个工具）	否	GITLAB_TOOLSETS=tags
snippets（5 个工具）	否	GITLAB_TOOLSETS=snippets
workitems（18 个工具）	否	GITLAB_TOOLSETS=workitems
webhooks（6 个工具）	否	GITLAB_TOOLSETS=webhooks
search（3 个工具）	否	GITLAB_TOOLSETS=search
variables（10 个工具）	否	GITLAB_TOOLSETS=variables
dependency_proxy（4 个工具）	否	GITLAB_TOOLSETS=dependency_proxy
vulnerabilities（4 个工具）	否	GITLAB_TOOLSETS=vulnerabilities
orbit（4 个工具）	否	GITLAB_TOOLSETS=orbit
api（1 个工具）	否	仅限 GITLAB_TOOLSETS=api（不包括 all、discover_tools 或 GITLAB_TOOLS）

启用所有可发现的工具集：GITLAB_TOOLSETS=all（不会启用 api）。若要恢复精简默认设置前的配置，请使用 GITLAB_TOOLSETS=merge_requests,issues,repositories,branches,projects,labels,ci,groups,users。使用 GITLAB_TOOLS 可启用工具集之外的单个工具，但显式启用的工具（如 gitlab_api_request）除外。discover_tools 可以列出并激活当前会话的可选类别，但不包括 api。execute_graphql 不属于任何工具集；请使用 GITLAB_TOOLS=execute_graphql 显式启用。USE_GITLAB_WIKI、USE_MILESTONE 和 USE_PIPELINE 已弃用（将在下一个主版本（v3.0.0）中移除）。如果已经设置了 GITLAB_TOOLSETS，请将工具集追加到现有列表，而不是替换列表。如果未设置 GITLAB_TOOLS，请设置 GITLAB_TOOLS=validate_ci_lint,validate_project_ci_lint。如果已设置，请将这两个工具追加到列表，而不是替换列表。

gitlab_api_request 不受 GITLAB_ALLOWED_GROUPS 和其他组限制、项目允许列表、工具级限制（其他工具上的 GITLAB_TOOLS、GITLAB_DENIED_TOOLS_REGEX）以及各个工具的安全检查约束。它会暴露完整的令牌权限范围。提示词注入可能会驱动此工具。依赖这些限制的运营者绝不能启用它。如果设置了 GITLAB_ALLOWED_PROJECT_IDS 或会话项目范围，则仅接受指向允许项目的 /projects/:id 路径；/search、/users、/groups/:id、/runners 和其他路径都会被拒绝。请求正文和查询参数中指定其他项目的内容不会经过检查。不会强制执行 GITLAB_PROJECT_ID 和 OAuth 组允许列表。

上方各工具集的数量总和为 315，因为 38 个 core 工具也分别列在其完整类别中（get_branch 和 list_branches 还同时列在 merge_requests 和 branches 中）；所有工具集中的唯一工具总数为 275。

关键工作流

代码审查（参见 reference/code-review.md）

1. list_merge_request_changed_files - 仅获取文件路径（不含差异）
2. get_merge_request_file_diff - 每次调用批量获取 3–5 个文件的差异
3. create_merge_request_thread 或 create_draft_note - 留下审查评论
4. bulk_publish_draft_notes - 一次性发布所有草稿

MR 生命周期（参见 reference/merge-requests.md）

create_merge_request -> 审查 -> approve_merge_request -> merge_merge_request

问题管理（参见 reference/issues.md）

create_issue -> create_issue_link -> create_issue_note -> update_issue

对于较长问题描述的小幅修改，请使用 update_issue_description_patch，而不是重新发送完整正文。

项目与命名空间

• get_project、list_projects、update_project - 查看或更改项目设置
• list_project_members、list_group_members - 在项目或群组中按姓名或用户名搜索成员
• list_namespaces、get_namespace、verify_namespace - 创建项目或群组前查找目标命名空间
• verify_namespace.parent_id 用于限定嵌套命名空间检查的范围
• create_repository.namespace_id 可在群组命名空间下创建项目

分支与提交

• create_branch、list_branches、get_branch、delete_branch
• 受保护分支：list_protected_branches、get_protected_branch、protect_branch、update_protected_branch、unprotect_branch、update_default_branch（protect_branch 只会创建规则；如果规则已存在，则返回 409。请使用来自 get_protected_branch 的记录 id 调用 update_protected_branch 来更改现有规则，而不是先取消保护再重新保护）
• 提交：list_commits、get_commit、get_commit_diff、get_file_blame、list_commit_statuses、create_commit_status

标签

• list_tags、get_tag、create_tag、delete_tag、get_tag_signature
• 受保护标签：list_protected_tags、get_protected_tag、protect_tag、unprotect_tag（create_access_level 为 0、30 或 40；支持 v* 等通配符）

CI

• 检查配置：validate_ci_lint、validate_project_ci_lint
• 目录：list_ci_catalog_resources、get_ci_catalog_resource
• 流水线／作业／部署：参见 reference/pipelines.md

工作项（参见 reference/work-items.md）

list_work_items -> get_work_item -> update_work_item -> create_work_item_note

变量与依赖代理

使用 GITLAB_TOOLSETS=variables 或 GITLAB_TOOLSETS=dependency_proxy 启用。

• 变量：项目／群组 CRUD 工具（list_*_variables、get_*_variable、create_*_variable、update_*_variable、delete_*_variable）
• 依赖代理：get_dependency_proxy_settings、update_dependency_proxy_settings、list_dependency_proxy_blobs、purge_dependency_proxy_cache

Webhook 与搜索

• Webhook：参见 reference/webhooks.md
• 代码搜索：参见 reference/search.md

漏洞分流（参见 reference/vulnerability-triage.md）

使用 GITLAB_TOOLSETS=vulnerabilities 启用（需要 GitLab Ultimate）。

list_project_vulnerabilities -> get_vulnerability -> dismiss_vulnerability 或 confirm_vulnerability

文件操作

• 读取：get_file_contents、get_repository_tree
• 写入：create_or_update_file（单个文件）、push_files（在一次提交中写入多个文件）

节省令牌的规则

• 不要将完整的 get_merge_request_diffs 载荷全部输出到对话中。先用 list_merge_request_changed_files 列出路径，然后每次调用 get_merge_request_file_diff 获取 3–5 个文件。
• 在让模型读取大型 JSON 响应前，优先使用 jmespath 筛选器或 GITLAB_MCP_COMPACT_RESULTS／--compact-results。
• 使用 limit 和 offset 对 get_pipeline_job_output 进行分页，而不是一次调用获取完整作业日志。

参数提示

• project_id：数字 ID 或 URL 编码的路径（group%2Fsubgroup%2Fproject）
• namespace_id：用于 create_repository 的数字命名空间 ID；请先使用 list_namespaces/verify_namespace
• parent_id：指定子群组创建范围，或用于嵌套群组的 verify_namespace
• MR 查找：提供 merge_request_iid 或 source_branch
• list_issues：默认范围 = 当前用户创建的问题。使用 scope: "all" 获取所有问题
• list_merge_requests：不提供 project_id 时，返回用户在所有项目中的 MR
• rebase_merge_request：wait 为 true（默认值）时，会返回合并请求以及 previous_sha 和 head_changed
• CI 目录资源查找：必须且只能提供 id 或 full_path 其中之一
• emoji reactions：合并请求、问题和工作项的反应工具使用 GitLab emoji 名称，如 thumbsup、rocket 或 eyes
• work items：状态和自定义字段需要 GitLab Premium/Ultimate 功能
• execute_graphql：在查询字符串中转义双引号

破坏性工具（请谨慎使用）

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

高级功能

• 动态发现：discover_tools 可在运行时列出并启用选择加入的工具集。它无法启用 api
• 工作流指南：help 可按需提供指南（代码审查、流水线、问题、节省令牌）。省略主题可查看概览
• 原始 API：仅当 GITLAB_TOOLSETS 包含 api 时才能使用 gitlab_api_request。只读模式仅允许 GET；修改模式会拒绝 DELETE
• GraphQL：对于 REST 工具未涵盖的查询，使用 execute_graphql
• 工具文档：docs/tools/ 根据 tools/registry.ts 生成；如需准确的架构定义，请优先查阅该目录
• 远程 MCP OAuth：当 GITLAB_MCP_OAUTH=true 时，POST /register（DCR）会按客户端 IP 限流（默认通过 MCP SDK 限制为 20 次/小时；可通过 OAUTH_REGISTER_RATE_LIMIT_PER_HOUR 调整）。此限制独立于 MAX_REQUESTS_PER_MINUTE 和 GitLab API 配额——请参阅 environment-variables.md
• Zoekt 搜索：search_code、search_project_code、search_group_code（需要启用高级搜索）
• 工作项：基于 GraphQL 的问题替代方案（Premium/Ultimate 功能）