内容
# GitLab 扩展 MCP
一款适用于 Claude Code 的高效 MCP 服务器，取代并扩展了官方的 Claude GitLab 插件。
- **38 个工具**，而官方插件只有 14 个
- **精简响应** — 原始 GitLab 对象仅包含有用字段
- **差异截断**，每个文件最多 150 行，并带有 `[...truncated]` 标记
- **系统注释过滤**，从讨论和问题评论中移除
- **空值移除**，通过 `_compact()` 从每个响应中移除
---
## 工具
### 合并请求
| 工具 | 描述 |
|---|---|
| `get_merge_request` | 单个合并请求 — 精简至约 15 个字段，包括 `diff_refs` |
| `list_project_mrs` | 列出合并请求，支持状态 / 作者 / 标签 / 分支过滤 |
| `create_merge_request` | 创建新的合并请求 |
| `update_mr` | 更新标题、描述、标签、指派人或状态 |
| `get_merge_request_diffs` | 文件差异，每个文件最多 150 行 |
| `get_mr_diff_stats` | 每个文件的添加/删除计数，不包含差异内容 |
| `get_merge_request_commits` | 合并请求中的提交（SHA、标题、作者、日期） |
| `get_merge_request_conflicts` | 冲突合并请求的原始 Git 冲突标记 |
| `get_merge_request_pipelines` | 为合并请求触发的流水线 |
| `get_mr_discussions` | 讨论线程及回复 — 系统事件已移除 |
| `get_mr_approvals` | 审批状态、审批人列表、所需计数 |
| `get_mr_participants` | 所有参与合并请求的用户 |
| `create_mr_note` | 在合并请求上发布一般性评论 |
| `create_mr_inline_note` | 在特定文件/行上发布内联差异评论 |
| `reply_to_mr_discussion` | 回复现有的讨论线程 |
| `resolve_mr_discussion` | 解决或取消解决讨论线程 |
### 问题
| 工具 | 描述 |
|---|---|
| `get_issue` | 单个问题 — 精简至约 10 个字段 |
| `list_project_issues` | 列出问题，支持状态 / 标签 / 指派人过滤 |
| `create_issue` | 创建新的问题 |
| `update_issue` | 更新标题、标签、指派人或状态 |
| `get_issue_notes` | 问题评论 — 系统事件已移除 |
| `create_issue_note` | 在问题上发布评论 |
### 工作项（官方插件对等）
| 工具 | 描述 |
|---|---|
| `get_workitem_notes` | 工作项（问题）的注释 |
| `create_workitem_note` | 在工作项上创建注释 |
### 流水线和 CI
| 工具 | 描述 |
|---|---|
| `manage_pipeline` | 列出 / 创建 / 重试 / 取消流水线 |
| `list_project_pipelines` | 列出流水线，支持状态和引用过滤 |
| `get_pipeline_jobs` | 流水线中的作业（ID、名称、阶段、状态、持续时间） |
| `get_pipeline_job_log` | 作业日志的最后 N 行 |
| `retry_job` | 重试失败或已取消的作业 |
| `cancel_job` | 取消正在运行的作业 |
### 仓库
| 工具 | 描述 |
|---|---|
| `get_file_at_ref` | 在分支、标签或提交 SHA 处的原始文件内容 |
| `list_repository_tree` | 在路径处浏览文件和目录 |
| `list_commits` | 分支的提交历史，可选按路径过滤 |
| `compare_refs` | 两个分支或 SHA 之间的差异 |
### 项目和搜索
| 工具 | 描述 |
|---|---|
| `get_project` | 项目元数据（默认分支、可见性、开放问题） |
| `create_project` | 创建新项目（可见性、命名空间、README 初始化） |
| `search` | 搜索问题、合并请求、blob、提交、注释、用户 |
| `search_labels` | 在项目或组中搜索标签 |
| `list_project_labels` | 列出项目的所有标签 |
| `list_project_members` | 具有访问级别的成员 |
| `list_project_variables` | CI/CD 变量键（GitLab 隐藏掩码值） |
---
## 设置
### 选项 A — Docker（推荐）
拉取预构建的多架构镜像（amd64 + arm64）：
```bash
docker pull YOUR_DOCKERHUB_USERNAME/gitlab-extended-mcp:latest
```
使用 Codex 注册：
```bash
codex mcp add gitlab-extended \
-- docker run --rm -i \
-e GITLAB_URL=https://gitlab.example.com \
-e GITLAB_TOKEN=glpat-your-token \
YOUR_DOCKERHUB_USERNAME/gitlab-extended-mcp:latest
```
使用 Claude Code 注册：
```bash
claude mcp add gitlab-extended \
--scope user \
-- docker run --rm -i \
-e GITLAB_URL=https://gitlab.example.com \
-e GITLAB_TOKEN=glpat-your-token \
YOUR_DOCKERHUB_USERNAME/gitlab-extended-mcp:latest
```
### 选项 B — 本地构建
```bash
git clone https://github.com/YOUR_GITHUB_USERNAME/gitlab-extended-mcp.git
cd gitlab-extended-mcp
docker build -t gitlab-extended-mcp .
```
使用 Codex 注册：
```bash
codex mcp add gitlab-extended \
-- docker run --rm -i \
-e GITLAB_URL=https://gitlab.example.com \
-e GITLAB_TOKEN=glpat-your-token \
gitlab-extended-mcp
```
使用 Claude Code 注册：
```bash
claude mcp add gitlab-extended \
--scope user \
-- docker run --rm -i \
-e GITLAB_URL=https://gitlab.example.com \
-e GITLAB_TOKEN=glpat-your-token \
gitlab-extended-mcp
```
### 选项 C — 直接使用 Python
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
GITLAB_URL=https://gitlab.example.com \
GITLAB_TOKEN=glpat-your-token \
python server.py
```
使用 Codex 注册：
```bash
codex mcp add gitlab-extended \
--env GITLAB_URL=https://gitlab.example.com \
--env GITLAB_TOKEN=glpat-your-token \
-- /path/to/.venv/bin/python /path/to/server.py
```
使用 Claude Code 注册：
```bash
claude mcp add gitlab-extended \
-e GITLAB_URL=https://gitlab.example.com \
-e GITLAB_TOKEN=glpat-your-token \
--scope user \
-- /path/to/.venv/bin/python /path/to/server.py
```
---
## 认证
需要具有 `api` 作用域的 GitLab 个人访问令牌。
GitLab → 用户设置 → 访问令牌 → 新令牌 → 选择 `api`。
---
## 令牌效率
| | 官方插件 | 此服务器 |
|---|---|---|
| 合并请求对象字段 | ~50 | ~15 |
| 每个文件的差异行 | 无限制 | 限制为 150 |
| 系统注释 | 已包含 | 已移除 |
| 空字段 | 已包含 | 已移除 |
| 提交 SHA | 40 个字符 | 8 个字符 |
| 用户对象 | 完整（8+ 个字段） | 仅 `username` |
典型的合并请求审查工作流程与官方插件相比，**减少 40–60% 的令牌使用**。
