GitLab MCP 服务器

一个用于 GitLab 集成的模型上下文协议（MCP）服务器。该服务器使 Claude 等 AI 助手能够访问 GitLab 仓库，辅助代码审查。

功能特性

• 合并请求工具

  • 获取 MR 详情、提交记录和代码变更
  • 支持完整的 GitLab URL 或独立参数

• 提交工具

  • 获取提交详情和差异对比
  • 支持完整的 GitLab URL 或独立参数

• URL 解析

  • 自动从 GitLab URL 中提取项目路径和资源 ID
  • 支持提交和合并请求 URL

系统要求

• Node.js >= 18.0.0
• 具有 read_api 权限的 GitLab 个人访问令牌
• GitLab CE 13.10.2+（已在 CE 13.10.2 上测试）

安装

# 克隆仓库
git clone <repository-url>
cd gitlab-mcp-server-ts

# 安装依赖
npm install

# 构建项目
npm run build

配置

设置以下环境变量：

export GITLAB_URL="http://your-gitlab-instance.com"
export GITLAB_TOKEN="your-personal-access-token"

可选配置：

export GITLAB_TIMEOUT="30000"  # 请求超时时间（毫秒），默认：30000

配置示例

示例 1：无线团队 GitLab 实例

export GITLAB_URL="http://192.168.11.252"
export GITLAB_TOKEN="your-personal-access-token"

示例 2：交换机团队 GitLab 实例

export GITLAB_URL="http://192.168.11.18:8081"
export GITLAB_TOKEN="your-personal-access-token"

如何获取个人访问令牌

1. 登录 GitLab 实例
2. 进入 用户设置 > 访问令牌
3. 创建新令牌，勾选 api 和 read_repository 权限
4. 复制生成的令牌

Claude Desktop 集成

将服务器添加到 Claude Desktop 配置中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/path/to/gitlab-mcp-server-ts/dist/index.js"],
      "env": {
        "GITLAB_URL": "http://192.168.11.252",
        "GITLAB_TOKEN": "your-personal-access-token"
      }
    }
  }
}

可用工具

get_merge_request

获取 GitLab 合并请求的详情。

参数：

• url（可选）：完整的 GitLab 合并请求 URL
• project（可选）：项目路径（例如 namespace/project）
• mrIid（可选）：合并请求 IID

示例：

获取 http://192.168.11.252/RAP_SD-Branch/EOS/-/merge_requests/123 的 MR 详情

get_mr_commits

获取 GitLab 合并请求中的提交列表。

参数：

• url（可选）：完整的 GitLab 合并请求 URL
• project（可选）：项目路径
• mrIid（可选）：合并请求 IID

get_mr_changes

获取 GitLab 合并请求中的文件变更（差异对比）。

参数：

• url（可选）：完整的 GitLab 合并请求 URL
• project（可选）：项目路径
• mrIid（可选）：合并请求 IID

get_commit

获取 GitLab 提交的详情。

参数：

• url（可选）：完整的 GitLab 提交 URL
• project（可选）：项目路径
• sha（可选）：提交 SHA

示例：

获取 http://192.168.11.252/RAP_SD-Branch/EOS/-/commit/11ab7d0e96e95d56fd370b36325d84c62270a697 的提交详情

get_commit_diff

获取 GitLab 提交的差异对比。

参数：

• url（可选）：完整的 GitLab 提交 URL
• project（可选）：项目路径
• sha（可选）：提交 SHA

URL 格式支持

服务器支持以下 GitLab URL 格式：

提交 URL：

http://192.168.11.252/RAP_SD-Branch/EOS/-/commit/11ab7d0e96e95d56fd370b36325d84c62270a697

合并请求 URL：

http://192.168.11.252/RAP_SD-Branch/EOS/-/merge_requests/123

项目路径格式（用于 project 参数）：

RAP_SD-Branch/EOS
hap/HOS-AX
switch/HAOS-RTK

GitLab CE 13.10.2 兼容性说明

本服务器针对 GitLab CE 13.10.2 进行了兼容性优化：

API 端点

• 使用 /api/v4 标准 API 路径
• 支持项目路径或 project_id 两种方式访问

权限要求

• 个人访问令牌需要 api 或 read_api 权限
• 对于 open 状态的 MR，某些 API 可能有访问限制

已知限制

• Open 状态的 MR 提交访问可能受限（GitLab CE 13.x 限制）
• 建议使用 merged 状态的 MR 进行代码审查

错误处理

服务器为常见问题提供清晰的错误信息：

• 401 Unauthorized：请检查你的 GITLAB_TOKEN
• 403 Forbidden：令牌可能缺少所需权限
• 404 Not Found：资源或项目不存在
• Timeout：请求超时（请调整 GITLAB_TIMEOUT）

许可证

MIT