GitLab-MCP-服务器

Name: GitLab-MCP-服务器
Author: amirsina-mandegari

作者：amirsina-mandegari15 星标更新：2025-11-10

安装使用来源：spider==github.com

项目介绍

GitLab MCP 服务器

将您的AI助手连接到GitLab。您可以在聊天中直接询问诸如_"列出打开的合并请求", "显示MR #123的评论", "获取MR #456的提交讨论", 或者"查找特性分支的合并请求"_等问题。

快速设置

先决条件

此项目使用 uv 进行快速可靠的Python包管理。

安装uv：

# macOS 和 Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 或使用pip
pip install uv

安装

安装服务器：

git clone https://github.com/amirsina-mandegari/gitlab-mcp-server.git
cd gitlab-mcp-server
uv venv
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate
uv pip install -e .
chmod +x run-mcp.sh

获取您的GitLab令牌：
- 转到 GitLab → 设置 → 访问令牌
- 创建具有 read_api 范围的令牌
- 复制令牌

配置您的项目： 在您的项目目录中创建 gitlab-mcp.env 文件：

GITLAB_PROJECT_ID=12345
GITLAB_ACCESS_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
GITLAB_URL=https://gitlab.com

连接到Cursor： 在您的项目中创建 .cursor/mcp.json 文件：

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "/path/to/gitlab-mcp-server/run-mcp.sh",
      "cwd": "/path/to/your-project"
    }
  }
}

重启Cursor 并开始提问！

您可以做什么

一旦连接成功，尝试在聊天中使用以下命令：

"列出打开的合并请求"
"显示合并请求456的详细信息"
"获取MR #123的评论和讨论"
"显示MR #456的测试总结"
"在合并请求#789中哪些测试失败了？"
"显示MR #456的流水线"
"获取合并请求#789的失败作业日志"
"显示MR #456的提交讨论"
"获取合并请求#789中的所有提交评论"
"查找feature/auth-improvements分支的合并请求"
"显示目标为主分支的已关闭合并请求"
"在MR #456的讨论abc123中回复'感谢反馈！'"
"在MR #789中创建新的审查评论，询问错误处理问题"
"解决MR #123中的讨论def456"

使用审查评论

增强的审查工具允许您与合并请求讨论进行交互：

首先获取审查 以查看讨论ID：
```
"显示MR #123的评论"
```

回复特定讨论 使用讨论ID：

"在MR #456的讨论abc123中回复'I将在下次提交中修复这个'"

创建新的讨论线程 开始对话：

"在MR #789中创建一个审查评论，询问'这里能否添加错误处理？'"

解决讨论 当问题得到解决时：
```
"解决MR #123中的讨论def456"
```

注意：get_merge_request_reviews 工具现在会在输出中显示讨论ID和注释ID，使得在回复或解决讨论时更容易引用特定讨论。

使用测试报告（推荐用于测试失败）

GitLab提供了两种检查测试结果的工具——使用摘要进行快速检查，使用完整报告进行详细调试：

选项1：测试摘要（快速且轻量）⚡

使用 get_pipeline_test_summary 获取快速概览：

"显示MR #123的测试摘要"
"在MR #456中有多少测试通过了？"

您会获得：

📊 每个测试套件的通过/失败数量
⏱ 总执行时间
🎯 通过率百分比
⚡ 快速 — 不包括详细的错误消息

选项2：完整测试报告（详细）🔍

使用 get_merge_request_test_report 进行详细调试：

"显示MR #123的测试报告"
"在合并请求#456中哪些测试失败了？"

您会获得：

✅ 具体的测试名称 通过/失败
❌ 错误消息 和堆栈跟踪
📦 测试套件 按类/文件组织
⏱ 每个测试的执行时间
📊 通过率 和汇总统计数据
📄 文件路径 和行号

两者如何工作：

自动获取合并请求的最新流水线
从该流水线检索测试数据（使用GitLab的 /pipelines/:pipeline_id/test_report 或 /test_report_summary API）

示例输出：

测试报告摘要：
总计：45个测试 | ✅ 42个通过 | ❌ 3个失败 | 通过率：93.3%

❌ 失败的测试：
  test_login_with_invalid_password (0.3秒)
    错误：AssertionError: 预期401，实际收到200
    文件：tests/auth_test.py

为什么使用这个而不是作业日志？

🎯 无噪音：只有测试结果，没有构建/设置输出
📊 结构化数据：易于AI理解并建议修复
🚀 快速：远小于完整的作业日志
🔍 精确：显示确切的测试名称和错误位置

需求：

您的CI必须使用 artifacts:reports:junit 在 .gitlab-ci.yml 中上传测试结果：

test:
  script:
    - pytest --junitxml=report.xml
  artifacts:
    reports:
      junit: report.xml

使用流水线作业和日志

流水线工具提供了一个两步流程来调试测试失败：

第一步：获取流水线概览

使用 get_merge_request_pipeline 查看所有作业及其状态：

"显示MR #456的流水线"

您会获得：

流水线概览（状态、持续时间、覆盖率）
按状态分组的所有作业（失败、运行中、成功）
每个作业的 作业ID （用于获取日志）
直接链接以在GitLab中查看作业
作业级别的计时和阶段信息

第二步：获取特定作业日志

使用 get_job_log 和作业ID获取实际输出：

"获取作业12345的日志"
"显示作业67890的输出"

您会获得：

完整的作业输出/跟踪
日志大小和行数
对于非常长的日志，自动截断到最后15,000个字符

典型的工作流程：

您："显示MR #123的流水线"
AI："流水线失败。有2个作业失败：
     - test-unit (作业ID：12345)
     - test-integration (作业ID：67890)"

您："获取作业12345的日志"
AI：[显示完整的测试输出及错误详情]

您："修复失败的测试"
AI：[分析日志并建议修复]

为什么需要两个工具？

性能：仅在需要时获取日志（不是一次性获取所有）
灵活性：检查任何作业的日志（失败、成功的或正在运行的）
上下文高效：避免不必要的大量日志倾倒

使用提交讨论

get_commit_discussions 工具提供了对合并请求内单个提交的讨论和评论的全面洞察：

查看合并请求中的所有提交讨论：
```
"显示MR #123的提交讨论"
```

获取详细的提交对话历史：

"获取合并请求#456中的所有提交评论"

此工具特别适用于：

代码审查跟踪：查看特定提交的所有反馈
讨论历史：了解代码讨论的发展历程
提交级别上下文：查看与特定代码更改相关的评论
审查进度：监控哪些提交已被讨论

技术实现：

使用 /projects/:project_id/merge_requests/:merge_request_iid/commits 获取所有提交，并正确分页
使用 /projects/:project_id/merge_requests/:merge_request_iid/discussions 获取所有合并请求讨论，并支持分页
使用位置数据过滤讨论以显示特定提交的讨论
正确处理单独评论和讨论线程

输出包括：

提交总数和讨论数量的摘要
单个提交的详细信息（SHA、标题、作者、日期）
每个提交的所有讨论和评论，带有文件位置
完整的对话线程及其回复
与差异相关的评论的文件位置
带有回复的线程对话

配置选项

项目级别（推荐）

每个项目都有自己的 gitlab-mcp.env 文件，包含其自己的GitLab配置。确保将令牌保留在版本控制之外。

全局配置

设置系统范围的环境变量，而不是每个项目：

export GITLAB_PROJECT_ID=12345
export GITLAB_ACCESS_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
export GITLAB_URL=https://gitlab.com

查找您的项目ID

转到您的GitLab项目 → 设置 → 通用 → 项目ID
或检查URL：https://gitlab.com/username/project（使用数字ID）

故障排除

认证错误：验证您的令牌具有 read_api 权限并且未过期。

项目未找到：双检查您的项目ID是否正确（它是一个数字，不是项目名称）。

连接问题：确保您的GitLab URL可访问且正确。

脚本未找到：确保MCP配置中的路径指向实际服务器位置，并且脚本是可执行的。

工具参考

工具	描述	参数
`list_merge_requests`	列出合并请求	`state`, `target_branch`, `limit`
`get_merge_request_details`	获取MR详细信息	`merge_request_iid`
`get_pipeline_test_summary`	获取测试摘要（快速概览）	`merge_request_iid`
`get_merge_request_test_report`	获取详细的测试失败报告	`merge_request_iid`
`get_merge_request_pipeline`	获取包含所有作业的流水线	`merge_request_iid`
`get_job_log`	获取特定作业的跟踪/输出	`job_id`
`get_merge_request_reviews`	获取评论/讨论	`merge_request_iid`
`get_commit_discussions`	获取提交上的讨论	`merge_request_iid`
`get_branch_merge_requests`	查找分支的MR	`branch_name`
`reply_to_review_comment`	回复现有讨论	`merge_request_iid`, `discussion_id`, `body`
`create_review_comment`	创建新的讨论线程	`merge_request_iid`, `body`
`resolve_review_discussion`	解决/取消解决讨论	`merge_request_iid`, `discussion_id`, `resolved`

从pip迁移到uv

如果您有一个使用pip的现有安装，这里是迁移至uv的方法：

安装uv（参见先决条件部分）

移除旧的虚拟环境：

deactivate  # 如果激活了虚拟环境
rm -rf .venv

使用uv创建新的虚拟环境：

uv venv
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate
uv pip install -e .

对于开发，安装开发依赖项：
```
uv pip install -e ".[dev]"
```

就这样！您的项目现在使用uv进行更快更可靠的依赖管理。

注意：requirements.txt 和 dev-requirements.txt 文件保留用于向后兼容。然而，pyproject.toml 现在是依赖项的事实来源。如果添加新依赖项，请更新 pyproject.toml 并根据需要重新生成需求文件：

uv pip compile pyproject.toml -o requirements.txt
uv pip compile --extra dev pyproject.toml -o dev-requirements.txt

开发

项目结构

gitlab-mcp-server/
├── main.py              # MCP服务器入口点
├── config.py            # 配置管理
├── gitlab_api.py        # GitLab API客户端
├── utils.py             # 实用函数
├── logging_config.py    # 日志配置
├── run-mcp.sh          # 启动脚本
└── tools/              # 工具实现包
    ├── __init__.py         # 包初始化
    ├── list_merge_requests.py
    ├── get_merge_request_details.py
    ├── get_merge_request_test_report.py
    ├── get_pipeline_test_summary.py
    ├── get_merge_request_pipeline.py
    ├── get_job_log.py
    ├── get_merge_request_reviews.py
    ├── get_commit_discussions.py
    ├── get_branch_merge_requests.py
    └── reply_to_review_comment.py

添加工具

在 tools/ 目录下创建新文件
在 tools/__init__.py 中添加导入和导出
在 main.py 中添加到 list_tools()
在 main.py 中添加到 call_tool()

开发设置

安装开发依赖项：

uv pip install -e ".[dev]"

设置预提交钩子：

pre-commit install

这将自动检查和格式化您的代码：

✨ 尾随空格 — 自动删除
📄 文件末尾问题 — 自动修复
🎨 代码格式化（black） — 自动格式化
📦 导入排序（isort） — 自动整理
🐍 Python风格（flake8） — 使用bugbear和打印检测进行linting
🔒 安全问题（bandit） — 安全检查
📋 YAML/JSON格式化 — 验证

格式化所有现有代码（首次仅需一次）：

# 如果尚未完成，请先安装依赖项
uv pip install -e ".[dev]"

# 格式化所有内容
black --line-length=120 .
isort --profile black --line-length=120 .

手动在所有文件上运行预提交：

pre-commit run --all-files

测试

python test_tools.py

安全注意事项

将 gitlab-mcp.env 添加到您的 .gitignore
绝不提交访问令牌
使用具有最小权限的项目特定令牌
定期轮换令牌

支持

查看 GitLab API 文档
在 github.com/amirsina-mandegari/gitlab-mcp-server 上打开问题

许可证

MIT 许可证 - 详见 LICENSE 文件。