GitLab MCP Server

GitLab MCP 服务（@sumirati/mcp-gitlab）

一款面向 2026 年、原生支持 AI 的 GitLab API v4 现代模型上下文协议（MCP）服务，专为自托管 GitLab Community Edition（CE）、Enterprise Edition（EE）和 GitLab.com 打造。

---

v3.0.0 的独特之处：2026 年 5 工具混合标准

早期的 MCP 服务会向客户端的工具列表中一次性塞入 50–100 个工具，每轮对话都要消耗 10,000+ 个提示词上下文令牌（“系统提示词税”），并且在 Glama TDQS 评分标准中的一致性评级较差。

@sumirati/mcp-gitlab v3 通过 5 工具混合界面解决了这一问题：

• Glama TDQS 一致性 A 级（5/5）：只向客户端公开 5 个工具，使服务处于理想的 3–15 个工具一致性最佳区间。
• 极低的系统提示词税：将架构开销从 27,681 个令牌降至 1,292 个令牌（减少 95.3%），保留上下文窗口，并最大限度地提高大模型提示词缓存命中率。
• 零跳转的高频操作：开发者和 Agent 在结对编程中经常使用的 3 项操作（get_file_contents、get_project、get_commit）仍作为即时工具，可立即零跳转执行。
• 按需访问 100% 平台功能：通过动态操作发现（gitlab_find_actions $\rightarrow$ gitlab_execute_action），可按需访问涵盖 14 个领域的 90 项操作，借助默认的高密度 Markdown 表格和摘要（format: "markdown" | "json"），节省 75%–96% 的令牌。
• 可靠的回退机制：如果 Agent 直接调用任何目录中的操作名称（例如 list_pipelines），服务会动态执行该操作，并进行完整的输入验证和投影。

LLM Prompt Context (1,292 tokens total):
├── 1. gitlab_find_actions(query, [domain], [format])     [Meta Discovery]
├── 2. gitlab_execute_action(action, params, [format])   [Meta Dynamic Execution]
├── 3. get_file_contents(project_id, file_path, [ref])    [Eager Daily Driver #1]
├── 4. get_project(project_id, [statistics])              [Eager Daily Driver #2]
└── 5. get_commit(project_id, sha)                        [Eager Daily Driver #3]

Under the hood (Dynamic Registry):
└── 90 Curated Actions across 14 Domains (with 75%–99% token reduction projections)

---

14 个领域的核心能力

1. 企业可观测性与自托管运维：
   • 系统健康诊断：端到端连接、令牌身份验证和 API 延迟测试（system_health_check）。
   • 推送镜像：验证向远程 Git 主机的上游复制（list_push_mirrors），并立即强制同步（trigger_push_mirror_sync）。
   • CI 运行器：审计运行器健康状况、在线／暂停状态和标签（list_runners、get_runner_status）。
   • Webhooks：检查已注册的自动化钩子（list_project_hooks）。
2. 仓库与分支治理：项目 CRUD、组层级解析（buggycode/project-name）、分支生命周期、分支保护管理（list_protected_branches、protect_branch、unprotect_branch）、文件／目录读取（get_file_contents）以及原子多文件提交（push_files、create_commit）。
3. CI/CD 可观测性：按状态查询流水线、触发／取消／重试流水线（create_pipeline、cancel_pipeline、retry_pipeline）、查看失败作业日志（get_job_trace）且不耗尽令牌额度、读取构建产物（get_job_artifact_file），以及检查 JUnit 测试报告（get_pipeline_test_report）。
4. 合并请求评审与差异讨论：两阶段差异检查（get_merge_request_changes）、自动清理锁文件（package-lock.json），以及带 SHA 坐标解析的行内差异讨论（create_diff_discussion）。
5. 议题与任务规划：议题 CRUD、跟踪阻塞项／依赖项（list_issue_links、create_issue_link），并添加进度备注（list_issue_notes、create_issue_note）。
6. 里程碑与标签：以易读形式解析里程碑、创建标签，以及检查指定范围内的里程碑。
7. Wiki 与代码片段：文档大纲切片（toc_only: true）、章节提取，以及代码片段管理。
8. 用户与身份上下文：查询已认证身份、枚举和创建群组（create_group），以及发现拥有的项目。

---

快速入门与安装

选项 1：使用 npx 运行（无需安装）

npx -y @sumirati/mcp-gitlab

选项 2：全局安装

npm install -g @sumirati/mcp-gitlab
mcp-gitlab

选项 3：本地克隆

git clone https://github.com/sumirati/mcp-gitlab.git
cd mcp-gitlab
npm install
npm test
npm start

---

环境配置

变量	必需	默认值	描述
GITLAB_PERSONAL_ACCESS_TOKEN	是	—	具有 api 范围的个人访问令牌。
GITLAB_API_URL	否	https://gitlab.com/api/v4	GitLab CE/EE 或云实例的基础 API URL。
GITLAB_READ_ONLY	否	false	启用只读安全模式（true、1、yes）。过滤掉会修改数据的工具，并严格阻止所有 90 个操作中的写入／修改 HTTP 请求。
GITLAB_EXPOSE_ALL_TOOLS	否	false	设置为 true（或 GITLAB_EXPOSE_LEGACY_TOOLS=true）以禁用 5 工具混合界面，并通过 ListTools 直接公开全部 90 个工具，供旧版客户端使用。
MCP_OUTPUT_FORMAT	否	markdown	默认输出格式（markdown 用于紧凑表格／摘要，json 用于结构化对象）。

---

客户端配置

Google Antigravity / Claude Desktop / Cursor

添加到 MCP 配置文件（mcp_config.json 或 claude_desktop_config.json）：

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@sumirati/mcp-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<your-gitlab-token>",
        "GITLAB_API_URL": "https://gitlab.example.com/api/v4"
      }
    }
  }
}

---

完整操作目录参考（14 个领域中的 90 个操作）

全部 90 个操作都支持严格的输入验证和字段掩码投影：

1. 客户端可见的 5 个工具（混合模式）

工具	类型	描述
gitlab_find_actions	Meta	在所有 14 个领域中搜索并发现可用的 GitLab 操作，并显示精简的参数签名
gitlab_execute_action	Meta	执行发现的任意 GitLab 平台操作，并进行输入验证和令牌优化投影
get_file_contents	Eager	从任意分支或提交引用中读取解码后的文件内容、符号概览或目录列表，无需克隆
get_project	Eager	获取项目元数据、项目 ID、可见性、克隆 URL、主题和默认分支
get_commit	Eager	查看 Git 提交详情、作者信息以及受令牌数量限制的文件差异

2. 企业版和自托管操作（enterprise — 6 个操作）

操作	描述	是否会修改？
system_health_check	对 GitLab 实例执行端到端的连接、延迟和权限诊断。验证 API 可用性、身份验证身份、服务器版本/版本类型（在获准时）以及当前只读策略。	否
list_push_mirrors	列出为项目配置的远程推送镜像，包括同步状态、目标 URL 和最近的错误诊断信息。对于验证本地自托管实例与上游 GitLab 实例或远程 Git 主机之间的仓库同步至关重要。	否
trigger_push_mirror_sync	强制立即同步指定项目的远程推送镜像。当代码已在本地提交，且需要立即复制到上游而无需等待计划的后台同步间隔时使用。	是
list_runners	列出可用的 GitLab CI/CD Runner（实例、组或项目级），并说明其在线状态、启用/暂停状态及执行器类型。用于诊断 CI 流水线执行延迟、Runner 连接问题或缺少执行器标签。	否
get_runner_status	获取特定 CI/CD Runner 的完整详情和运行状况，包括 IP 地址、架构、Runner 版本、标签以及最近联系时间。用于排查卡住的作业或无响应的自托管 Runner。	否
list_project_hooks	列出已配置的项目 Webhook 及其订阅的触发事件（推送、合并请求、议题、流水线事件）。用于审查集成 Webhook，并验证 CI/CD 自动化钩子的注册情况。	否

3. 仓库与项目管理（repositories — 10 个操作）

操作	描述	是否会修改？
search_repositories	搜索整个实例中的 GitLab 项目和仓库，或限定在特定群组命名空间内搜索（建议采用此方式以减轻实例负载）。每页最多返回 100 条。如果已知 project_id 或 path_with_namespace，请直接通过 'get_project' 查询。	否
get_project	获取特定 GitLab 项目的完整元数据，包括默认分支、仓库统计信息、可见性和主题标签。可用于检查仓库设置或验证项目访问权限。不要用于检查目录树或源代码；请改用 'get_file_contents'。	否
create_repository	在个人命名空间或指定群组下创建新的 GitLab 项目／仓库。可用于创建新的代码库或初始化仓库。副作用：立即创建新的 GitLab 项目。不要用于复制现有项目；请改用 'fork_repository'。	是
update_project	更新可修改的项目设置，包括显示名称、描述、默认分支、可见性级别和主题。可用于修改仓库配置或管理信息。副作用：立即更改项目设置。不要用于提交代码更改；请改用 'create_or_update_file' 或 'push_files'。	是
delete_project	永久删除 GitLab 项目及其所有仓库文件、议题、合并请求和 CI/CD 流水线。仅用于停用项目。副作用：此操作具有破坏性且不可撤销。需要通过 confirm_project_name 明确确认安全性。	是
get_file_contents	从仓库的指定分支、标签或提交引用中读取特定文件或目录树的原始内容。可用于检查当前仓库源代码或配置。不要用于查看分支之间的差异（请改用 'get_merge_request_changes'）或查看提交差异（请改用 'get_commit'）。	否
create_or_update_file	在仓库中创建新文件或更新现有文件内容，并生成 Git 提交。可用于单文件更改或文档更新。副作用：立即在远程分支上创建 Git 提交。不要用于同时更新多个文件；如需原子性地提交多个文件，请改用 'push_files'。	是
push_files	在单个 Git 提交中，原子性地将多个文件的新增、修改或删除提交到目标分支。可用于多文件重构、功能开发或项目脚手架搭建。副作用：在远程分支上创建包含多个原子操作的 Git 提交。请使用此工具，而不要循环调用 'create_or_update_file'。	是
create_commit	使用 GitLab Commits API，在单个 Git 提交中原子性地将多个文件的新增、修改或更新提交到目标分支。无需在本地克隆 git 仓库，即可用于多文件重构、功能开发或项目脚手架搭建。副作用：在远程分支上创建包含多个原子操作的 Git 提交。	是
fork_repository	将现有 GitLab 项目分叉到指定用户命名空间或群组。可用于为上游项目贡献代码或创建独立分叉。副作用：创建一个关联到上游源项目的新仓库。不要用于创建全新的空项目；请改用 'create_repository'。	是

4. 分支治理（branches — 7 个操作）

操作	描述	是否修改？
list_branches	列出仓库分支及其最新提交摘要、默认分支标记和受保护状态。用于发现活跃开发分支或检查分支是否存在。不要用它检查提交差异（请使用 'get_commit'）或列出标签（请使用 'list_tags'）。	否
get_branch	获取特定 Git 分支的详细信息，包括最新提交 SHA、作者信息和分支保护规则。用于在创建合并请求前确认提交是否一致。不要用它直接检查文件内容；请改用 'get_file_contents'。	否
create_branch	从现有分支、标签或提交 SHA 创建新的 Git 分支。用于初始化功能分支、修复分支或发布分支。副作用：在远程仓库中创建新的分支指针。不要用它创建新仓库；请改用 'create_repository'。	是
delete_branch	删除项目仓库中现有的 Git 分支。用于清理已合并或过时的功能分支。副作用：破坏性操作。为确保安全，系统会主动阻止意外删除项目的默认分支。不要用它删除标签；请使用 Git 标签管理。	是
list_protected_branches	列出 GitLab 项目中配置的受保护分支规则，显示推送／合并访问级别、强制推送权限和代码所有者审批要求。用于审计分支治理和合并限制。	否
protect_branch	为分支或通配符模式（例如 'main'、'release/*'）配置分支保护规则。控制推送访问级别、合并访问级别、强制推送权限和代码所有者审批要求。	是
unprotect_branch	移除指定分支或通配符模式的分支保护规则。副作用：破坏性操作。移除目标分支的推送和合并访问限制。	是

5. Git 提交与历史（commits — 2 个操作）

操作	描述	是否修改？
list_commits	按时间顺序列出项目、分支或特定文件路径的提交历史，并显示作者元数据和提交消息。可通过 ref_name、作者、路径和日期范围进行过滤。如需检查特定提交 SHA 的确切代码变更，请改用 'get_commit'。	否
get_commit	获取特定 Git 提交 SHA 的详细信息，包括作者信息、统计数据、已修改文件以及选定文件的统一差异。用于检查提交所做的确切代码变更。支持按 file_path 过滤并限制行数，以防大型提交耗尽上下文。	否

6. 流水线与 CI/CD 可观测性（pipelines — 10 个操作）

操作	描述	是否有修改？
list_pipelines	按分支、标签、状态（'running'、'success'、'failed'、'canceled'）或提交 SHA 筛选 CI/CD 流水线，并以节省令牌的方式汇总状态。用于检查部署状态、监控测试套件运行状况或确认构建触发情况。不要用于检查特定作业日志；请改用 'get_job_trace'。	否
get_pipeline	按数字 ID 获取特定 CI/CD 流水线的详细信息，包括执行状态、持续时间、排队时长及关联的提交信息。用于评估流水线运行状况或检查所有阶段是否已完成。不要用于检查单个作业的失败情况；请改用 'list_pipeline_jobs' 或 'get_job_trace'。	否
create_pipeline	手动触发并运行新的 CI/CD 流水线执行，可指定分支或标签，并可选自定义流水线变量。用于按需启动测试、构建或部署。副作用：立即在 GitLab runners 上启动作业执行。不要用于检查正在运行的作业；请改用 'list_pipeline_jobs'。	是
cancel_pipeline	按数字 pipeline_id 取消正在运行的 CI/CD 流水线执行中的所有运行中和待处理作业。副作用：立即终止此流水线的活动 runner 作业。	是
retry_pipeline	按数字 pipeline_id 重试现有 CI/CD 流水线执行中所有失败或已取消的作业。副作用：立即在 GitLab runners 上重新排队失败或已取消的作业。	是
list_pipeline_jobs	列出特定流水线中的所有执行作业（构建、测试、代码检查、部署）及其当前状态。用于确定流水线执行中具体哪个阶段或作业失败。不要用于下载作业输出日志；确认失败作业 ID 后，请改用 'get_job_trace'。	否
get_job	获取特定 CI/CD 作业的详细信息，包括持续时间、runner 标签、失败原因和可用的制品压缩包。用于诊断 runner 作业停滞或失败的原因。不要用于流式读取终端日志；请改用 'get_job_trace'。	否
get_job_trace	获取特定 CI/CD 作业的原始终端控制台输出日志，并可配置尾部行数（tail_lines）。用于检查编译错误、堆栈跟踪和测试断言失败，同时避免上下文溢出。不要用于检查结构化 JUnit 测试套件；请改用 'get_pipeline_test_report'。	否
get_job_artifact_file	从已完成作业的构建制品 zip 压缩包中下载并读取特定文件的文本内容（例如覆盖率报告、构建清单、测试输出）。用于检查生成的制品，而无需下载整个压缩包。不要用于仓库文件；请改用 'get_file_contents'。	否
get_pipeline_test_report	获取流水线执行的结构化 JUnit 测试摘要报告，包括测试总数、通过和失败的测试用例、执行时长及失败堆栈跟踪。用于诊断各测试套件中的自动化测试失败。不要用于查看原始控制台输出；请改用 'get_job_trace'。	否

7. 合并请求与代码审查（merge-requests — 12 个操作）

操作	描述	是否会修改？
list_merge_requests	按状态（'opened'、'closed'、'merged'、'all'）、源分支/目标分支、里程碑、标签、作者、受派人、审阅者或搜索文本筛选合并请求。搜索文本会直接发送到 GitLab 的索引数据库。架构最佳实践：对于已知合并请求，始终优先使用确切的 merge_request_iid 调用 'get_merge_request'，而非进行宽泛的列表查询。	否
get_merge_request	根据 IID（!）获取特定合并请求的完整详情，包括状态、可合并性、审批状态、分支名称、diff head SHA 和描述。用于评估审查状态或准备合并。请勿用此工具检查文件 diff；请改用 'get_merge_request_changes'。	否
create_merge_request	创建新的合并请求，将源分支中的更改合并到目标分支。支持设置标题、Markdown 描述、受派人、审阅者、里程碑和目标分支删除选项。副作用：立即在 GitLab 中创建新的 MR。请勿用此工具发布审查评论；请改用 'create_diff_discussion'。	是
update_merge_request	更新现有合并请求的标题、描述、目标分支、里程碑、标签、受派人或状态（'close' 或 'reopen'）。用于更新 MR 详情或关闭已过时的请求。副作用：立即更改 MR 配置。请勿用此工具合并 MR；请改用 'accept_merge_request'。	是
get_merge_request_changes	检查 MR 的统一代码 diff 和已修改文件。支持节省令牌的摘要（summary_only）、文件路径筛选、锁文件精简，以及自动获取内联评论所需的 diff refs（base_sha、start_sha、head_sha）。用于 AI 代码审查分析。	否
list_merge_request_discussions	列出合并请求中的内联代码审查讨论、评论线程和解决状态。支持筛选未解决的审查评论（unresolved_only: true）。用于审查待处理的代码评论或核实审查反馈。请勿用于一般项目议题评论；请改用 'list_issue_notes'。	否
create_diff_discussion	在 MR diff 中指定文件和行号处发起新的内联代码审查讨论线程。若未提供所需的 base_sha、start_sha 和 head_sha，会自动从 MR 中获取。用于代码审查时留下可执行的内联反馈。副作用：立即发布公开的审查讨论线程。	是
reply_merge_request_discussion	在合并请求中现有的代码审查讨论线程内发布回复评论。用于回应审查反馈或确认代码修复。副作用：立即向讨论线程添加回复备注。请勿用此工具解决讨论；请改用 'resolve_merge_request_discussion'。	是
update_merge_request_discussion_note	编辑或更新 MR 讨论线程中现有审查评论的文本。用于更正审查意见或更新代码建议。副作用：立即修改评论文本。请勿用此工具发布新评论；请改用 'reply_merge_request_discussion' 或 'create_diff_discussion'。	是
resolve_merge_request_discussion	解决或取消解决合并请求中的整个代码审查讨论线程。确认审查反馈已处理后使用。副作用：立即更新审查线程的解决状态。	是
accept_merge_request	将已批准的合并请求合并到其目标分支。支持压缩提交、自定义合并提交消息，以及在合并时删除源分支。副作用：立即合并分支并触发下游 CI/CD 部署流水线。若测试失败或审批尚未完成，请勿使用。	是
create_merge_request_note	在合并请求上发布顶层一般评论或审查摘要备注。用于整体审查摘要、LGTM 或测试执行报告。副作用：立即向 MR 发布一般备注。请勿用于针对特定行的 diff 审查反馈；请改用 'create_diff_discussion'。	是

8. 问题与路线图（issues — 8 个操作）

操作	描述	是否会修改？
list_issues	按状态（'opened'、'closed'、'all'）、里程碑、标签、作者、指派人或关键字搜索筛选项目问题；搜索会直接推送到 GitLab 的索引数据库。架构最佳实践：对于已知问题，始终优先使用带有确切 issue_iid 的 'get_issue'，而不是进行宽泛的列表查询。	否
get_issue	获取特定问题的完整详情，使用项目范围内的 IID（#），包括描述、指派人、标签、里程碑和问题状态。用于查看问题需求或跟踪解决进度。请勿用于列出问题评论；请改用 'list_issue_notes'。	否
create_issue	创建新问题，可设置标题、Markdown 描述、里程碑（按标题或 ID）、标签、指派人和可选的截止日期。用于报告 Bug、跟踪用户故事或规划任务。副作用：立即创建新的 GitLab 问题。请勿用于评论已有问题；请改用 'create_issue_note'。	是
update_issue	更新已有问题的标题、描述、状态（'close' 或 'reopen'）、里程碑、标签或指派人。用于推进问题生命周期或更新任务状态。副作用：立即更改问题状态。请勿用于发布进度评论；请改用 'create_issue_note'。	是
list_issue_notes	按 IID 列出特定问题的按时间顺序排列的讨论备注、用户评论和活动审计日志。用于查看问题讨论、过往评论或实施进度。请勿用于合并请求讨论；请改用 'list_merge_request_discussions'。	否
create_issue_note	向已有问题发布新的 Markdown 评论、进度更新或验证备注。用于交流发现、记录测试结果或询问任务相关问题。副作用：立即向问题讨论串发布公开评论。	是
list_issue_links	列出与特定问题关联的依赖关系链接（'relates_to'、'blocks'、'is_blocked_by'）。用于分析任务依赖关系或发布阻碍。请勿用于检查问题讨论备注；请改用 'list_issue_notes'。	否
create_issue_link	在两个问题之间创建依赖关系或关联链接（'relates_to'、'blocks'、'is_blocked_by'），可跨同一项目或不同项目。用于跟踪阻碍关系或关联的 Bug 报告。副作用：立即创建双向问题关联。	是

9. 里程碑与标签（milestones — 6 个操作）

操作	描述	是否会修改？
list_milestones	按状态（'active'、'closed'、'all'）筛选项目及上级群组的里程碑列表，包含开始日期、截止日期和进度。用于跟踪冲刺目标、发布目标或项目路线图。请勿用于查看里程碑中的单个议题列表；请改用带有里程碑筛选条件的 'list_issues'。	否
get_milestone	按数字 ID 获取特定项目里程碑的详细信息，包括描述、日期和状态。用于验证目标里程碑日期或检查里程碑进度。请勿用于列出项目里程碑；请改用 'list_milestones'。	否
create_milestone	创建新的项目里程碑，并设置标题、描述、开始日期和截止日期。用于规划发布版本、冲刺或交付路线图。副作用：立即创建新的项目里程碑。请勿用于创建发布；请改用 'create_release'。	是
update_milestone	更新现有里程碑的标题、描述、截止日期、开始日期或生命周期状态（'activate' 或 'close'）。用于调整发布计划或完成冲刺。副作用：立即更改里程碑元数据。	是
list_labels	列出项目中可用的标签（包括从上级群组继承的标签），以及颜色和描述。用于在为议题或合并请求分类前查找有效的分类标签。请勿用于创建新标签；请改用 'create_label'。	否
create_label	在项目中创建新标签，并设置名称、十六进制颜色代码和描述。用于建立项目工作流标记、优先级标记或组件分类。副作用：立即创建新的项目标签。	是

10. 发布与标签（releases — 5 个操作）

操作	描述	是否会修改？
list_releases	列出已发布的 GitLab 发布、版本标签、变更日志描述和关联资源。用于检查已发布的版本或查看发布历史。请勿用于查看没有发布说明的原始 Git 标签；请改用 'list_tags'。	否
get_release	按标签名称获取已发布版本的详细信息，包括 Markdown 发布说明、作者和可下载的资源链接。用于查看完整的发布说明或变更日志。请勿用于查看里程碑目标；请改用 'get_milestone'。	否
create_release	发布正式的 GitLab 版本，并将其关联到 Git 标签，其中包括标题、Markdown 变更日志说明和关联的里程碑标题。如果标签不存在，则必须提供 ref 才能创建该标签。副作用：创建正式的公开发布条目。请勿用于创建不带发布说明的标签；请改用 'create_tag'。	是
list_tags	列出仓库中的 Git 标签，以及对应的提交 SHA、发布链接和注释消息。用于创建标签前检查特定的发布标签是否已存在。请勿用于查看发布说明；请改用 'list_releases'。	否
create_tag	创建指向特定分支或提交 SHA 的带注释或轻量级 Git 标签。用于标记 Git 历史记录中的发布节点或版本里程碑。副作用：立即在远程仓库中创建新的 Git 标签。请勿用于发布完整的发布说明；请改用 'create_release'。	是

11. 项目协作者与角色（members — 5 个操作）

操作	描述	是否修改数据？
list_project_members	列出项目成员和协作者，以及其获分配的访问级别、角色和成员资格到期日期。支持筛选并包含继承的群组成员。用于审计项目权限，或在分配任务前检查协作者的访问权限。不要用它检查全局用户资料；请改用 'get_current_user'。	否
get_project_member	按数字 ID 或用户名检索特定用户在项目中的成员资格详情、访问级别和权限。用于确认协作者是否拥有 Developer 或 Maintainer 权限，再触发受保护的操作。不要用它搜索所有成员；请改用 'list_project_members'。	否
add_project_member	为用户授予项目访问权限，并指定角色（'guest'、'reporter'、'developer'、'maintainer'、'owner'）和可选的到期日期。自动解析用户名。副作用：立即授予仓库权限。不要用它更新现有成员资格；请改用 'update_project_member'。	是
update_project_member	更改项目中现有协作者的访问级别、角色或到期日期。自动解析用户名。副作用：立即更改项目访问控制。不要用它添加新成员；请改用 'add_project_member'。	是
remove_project_member	撤销协作者对项目仓库及相关资源的访问权限。副作用：对用户访问具有破坏性；会立即移除仓库权限。不要用它调整访问级别；请改用 'update_project_member'。	是

12. CI/CD 环境变量（variables — 5 个操作）

操作	描述	是否修改数据？
list_project_variables	列出为项目配置的所有 CI/CD 流水线变量，包括键、变量类型（'env_var' 或 'file'）、受保护/已屏蔽标志和环境作用域。用于在运行构建/部署流水线前确认密钥和配置是否存在。不要用它获取密钥值；请改用 'get_project_variable'。	否
get_project_variable	按键名检索特定 CI/CD 变量的完整详情和当前值。用于调试流水线环境故障或检查密钥值。不要用它列出所有已配置变量；请改用 'list_project_variables'。	否
create_project_variable	创建新的 CI/CD 流水线变量（'env_var' 或 'file'），并设置受保护、已屏蔽和环境作用域选项。用于配置构建密钥、令牌或环境配置。副作用：该变量会立即提供给 CI/CD 流水线作业使用。不要用它更新现有变量；请改用 'update_project_variable'。	是
update_project_variable	更新现有 CI/CD 变量的值、屏蔽状态、保护状态或环境作用域。用于轮换密钥或更新配置值。副作用：立即更改流水线执行环境。不要用它创建新变量；请改用 'create_project_variable'。	是
delete_project_variable	按键从项目中永久删除 CI/CD 流水线变量。用于撤销过期凭据或清理过时配置。副作用：具有破坏性；后续流水线运行将无法再访问此变量。	是

13. Wiki 与文档（wikis — 4 个操作）

操作	描述	是否会修改？
list_wikis	列出项目中的所有 Wiki 文档页面，包括页面 slug、标题和格式类型。用于查找可用的项目文档或指南。不要用于读取完整页面内容；请改用 'get_wiki'。	否
get_wiki	根据页面 slug 获取 Wiki 文档内容，并提供节省 token 的选项，包括结构化目录（toc_only: true）或定位到指定章节／标题部分（section: 'Heading'）。用于查阅项目架构指南，避免上下文过载。不要用于仓库文件；请改用 'get_file_contents'。	否
create_wiki	在项目中创建新的 Wiki 文档页面，并设置 Markdown 内容和格式选项。用于记录设置流程、架构或设计运行手册。副作用：立即创建新的项目 Wiki 页面。不要用于更新现有页面；请改用 'update_wiki'。	是
update_wiki	根据 slug 更新现有项目 Wiki 页面的 Markdown 内容或标题。用于更新持续维护的项目文档、运行手册或规范。副作用：立即更改 Wiki 页面内容。不要用于创建新的 Wiki 页面；请改用 'create_wiki'。	是

14. 代码片段与代码粘贴（snippets — 4 个操作）

操作	描述	是否会修改？
list_snippets	列出 GitLab 项目中发布的代码片段，包括作者详情、文件名和可见性级别（'private'、'internal'、'public'）。用于查找存储在项目代码片段中的实用脚本、SQL 查询或配置模板。不要用于检查原始代码片段代码；请改用 'get_snippet'。	否
get_snippet	根据数字 ID 获取特定代码片段的详细信息和原始文本内容。用于检查代码脚本、补丁或配置片段。不要用于仓库文件；请改用 'get_file_contents'。	否
create_snippet	在项目中创建新的代码或文本片段，并设置标题、文件名、Markdown 描述和可见性。用于分享调试脚本、一次性补丁或配置片段。副作用：立即创建新的 GitLab 代码片段。不要用于向 Git 仓库提交文件；请改用 'create_or_update_file'。	是
update_snippet	根据数字 ID 更新现有项目代码片段的代码内容、文件名、标题、描述或可见性。用于维护代码片段或调整访问权限。副作用：立即更改代码片段。不要用于创建新的代码片段；请改用 'create_snippet'。	是

15. 用户与群组上下文（user — 6 项操作）

操作	描述	是否有修改？
get_current_user	获取已认证 GitLab 账户的身份和个人资料详情（用户名、数字 ID、姓名、电子邮件、管理员标记）。用于验证令牌是否有效、检查当前权限，或查找自己的用户名以便分配任务。请勿用于查询其他用户的个人资料；请改用 'list_project_members'。	否
list_my_groups	列出已认证用户作为活跃成员或所有者并拥有访问角色的 GitLab 群组和上级组织。用于查找可用于创建项目或进行访问审计的命名空间路径。请勿用于直接查看项目列表；请改用 'list_group_projects'。	否
create_group	创建新的 GitLab 群组或嵌套子群组（使用 parent_id）。用于组织项目、管理团队命名空间并设置共享权限。副作用：立即在 GitLab 上创建新群组。	是
get_group	根据数字 ID 或完整路径（例如 'buggycode'）获取特定 GitLab 群组或命名空间的详细信息。用于检查群组级别的可见性、描述或上级群组层级。请勿用于列出群组中的项目；请改用 'list_group_projects'。	否
list_group_projects	分页列出特定 GitLab 群组或组织中的所有代码库和项目，并支持搜索。支持 include_subgroups（默认值：true）。用于查找团队或企业命名空间中的项目。请勿用于跨实例搜索项目；请改用 'search_repositories'。	否
list_my_projects	列出已认证用户作为直接成员、所有者或已加星标贡献者参与的 GitLab 项目，并提供角色摘要。用于查找个人代码库或已加星标的代码库。请勿用于在公开项目中进行通用文本搜索；请改用 'search_repositories'。	否

---

基准测试：实测令牌节省

可复现的确定性基准测试（node test/benchmark-test.js 和 node test/catalog-execution-test.js）以规范的 GitLab REST API v4 负载为基准（test/fixtures/gitlab-api-v4-fixtures.js，令牌数 = Math.ceil(utf8Bytes / 4)）：

操作	原始 GitLab API v4	@sumirati/mcp-gitlab（JSON）	@sumirati/mcp-gitlab（Markdown）	令牌减少量（MD）
系统提示词开销（5 个工具对比 90 项操作）	27,681 tokens	—	1,292 tokens	节省 95.3%
get_project（检查单个项目）	971 tokens	144 tokens	124 tokens	节省 87.2%
list_issues（含 v4 元数据的 10 个议题）	6,595 tokens	1,906 tokens	460 tokens	节省 93.0%
list_merge_requests（含 v4 元数据的 10 个合并请求）	6,377 tokens	1,058 tokens	423 tokens	节省 93.4%
list_pipelines（10 次运行）	880 tokens	543 tokens	212 tokens	节省 75.9%
get_file_contents（源文件，已剥离 Base64）	279 tokens	201 tokens	160 tokens	节省 42.7%
get_merge_request_changes（代码和锁文件差异）	3,612 tokens	156 tokens	141 tokens	节省 96.1%

完整的 90 项操作目录基准测试（涵盖全部 14 个领域）

通过 node test/catalog-execution-test.js 对全部 90 个处理程序进行测量：

领域	操作数	原始 GitLab v4 令牌数	投影后的 JSON	渲染后的 Markdown	令牌节省（MD）
仓库	10	8,966 个令牌	1,361 个令牌	728 个令牌	91.9%
分支	7	6,797 个令牌	326 个令牌	245 个令牌	96.4%
提交	2	1,942 个令牌	179 个令牌	125 个令牌	93.6%
成员	5	4,855 个令牌	197 个令牌	174 个令牌	96.4%
变量	5	4,855 个令牌	200 个令牌	191 个令牌	96.1%
议题	8	52,760 个令牌	6,454 个令牌	1,419 个令牌	97.3%
里程碑	6	39,570 个令牌	387 个令牌	217 个令牌	99.5%
流水线	10	65,950 个令牌	1,304 个令牌	726 个令牌	98.9%
发布	5	32,975 个令牌	185 个令牌	193 个令牌	99.4%
合并请求	12	79,140 个令牌	1,498 个令牌	867 个令牌	98.9%
Wiki	4	26,380 个令牌	65 个令牌	69 个令牌	99.7%
代码片段	4	26,380 个令牌	465 个令牌	453 个令牌	98.3%
用户	6	39,570 个令牌	249 个令牌	251 个令牌	99.4%
企业版	6	39,570 个令牌	245 个令牌	302 个令牌	99.2%
总计（全部 90 项操作）	90	429,710 个令牌	13,115 个令牌	5,960 个令牌	98.6%

令牌优化的关键支柱：

• 智能差异与锁文件截断：提交差异（get_commit）和 MR 更改（get_merge_request_changes）默认会通过 ignore_lockfiles: true 自动折叠依赖锁文件（package-lock.json、pnpm-lock.yaml、yarn.lock、go.sum、Cargo.lock、*.min.js），每次审查可节省 1,000–3,000 个令牌。如果需要完整的锁文件差异，请传入 ignore_lockfiles: false。
• 保守的默认分页：所有列表操作默认使用 per_page: 10（最大值：100），避免在只需要最近条目时加载 20–50 项造成令牌浪费。
• 默认使用高密度 Markdown 格式：发现操作（gitlab_find_actions）、执行操作（gitlab_execute_action）、项目信息（get_project）、文件检查（get_file_contents）和提交检查（get_commit）默认使用 format: "markdown"，可使结构化元数据的令牌用量减少 75%–96%。
• 递归输出投影过滤器（projectOutput）：在负载进入大模型上下文之前，剔除 GitLab REST API v4 的冗余元数据键（_links、avatar_url、references、time_stats、task_completion_status、commands_changes、user_notes_count、merge_requests_count、upvotes、downvotes、subscribed、has_tasks、service_desk_reply_to、moved_to_id、container_expiration_policy、permissions，以及空值和空字段）。

---

路线图

即将推出（v3.2）

• 上游索引过滤与严格的分页上限（state、labels、milestone、author_id、assignee_id）
• 客户端错误恢复能力（401 探测消歧、403 权限范围不足、429 速率限制退避、201 幽灵写入保护）
• 强化输出投影，增加递归深度保护（maxDepth = 32）并保留空集合
• 嵌套子组层级管理（create_group 使用 parent_id）
• 在 get_job_trace 中智能提取 CI/CD 失败日志并剥离 ANSI 序列（strip_ansi、smart_failure）
• 在 get_file_contents 中优先提取代码符号大纲并切片行范围（outline_only、start_line、end_line）
• 预先检查合并可行性与冲突（get_mergeability）
• 令牌范围自审计与权限预检查

未来展望（v3.x）

• 标准化集合 _summary 标头，便于在 LiteLLM / Eigent Agent 编排中裁剪多轮历史记录
• 远程传输：Streamable SSE 和 HTTP 远程服务模式
• 用于关系型深度检查的作用域限定 GraphQL 查询引擎
• DevSecOps 漏洞与密钥扫描告警查询
• 在项目代码库中进行带作用域限制和速率保护的代码搜索

---

致谢与渊源

本项目采用了以下项目的架构概念、架构和模式：

• @modelcontextprotocol/server-gitlab（MIT License）— Copyright (c) 2024 Anthropic, PBC / GitLab, PBC。基础代码库和文件架构模式。
• @modelcontextprotocol/sdk（MIT License）— Copyright (c) Anthropic, PBC。
• zod（MIT License）— Colin McDonnell。
• GitLab REST API v4 — GitLab, PBC。
• jmrplens/gitlab-mcp-server — 动态操作发现与元分派器模式概念。
• 参考评估了 Vijay-Duke/mcp-gitlab 和 zereight/gitlab-mcp 中的架构模式。

完整的第三方署名详情请参阅 NOTICE。

---

许可证

本项目采用 MIT License 授权 — Copyright (c) 2026 [email protected]。