GitLab Pipeline MCP Server

一个用于 GitLab 流水线操作的 Model Context Protocol (MCP) 服务器。

🎯 项目概述

本项目允许AI客户端（如Cursor、Claude Desktop等）通过自然语言直接操作GitLab流水线。

功能特性

• 🚀 触发 GitLab 流水线
• 📊 获取流水线状态
• 📋 列出流水线
• 🔧 获取流水线作业
• ❌ 取消流水线

安装

yarn install

环境变量配置

在使用前，请设置以下环境变量：

export GITLAB_URL="https://gitlab.example.com"
export GITLAB_PROJECT_ID="123"
export GITLAB_TOKEN="your-gitlab-token"

或者创建 .env 文件：

GITLAB_URL=https://gitlab.example.com
GITLAB_PROJECT_ID=123
GITLAB_TOKEN=your-gitlab-token

使用方式

1. STDIO 模式（标准输入输出）

适用于 MCP 客户端直接连接：

# 使用原版实现（支持所有5个工具）
yarn build

MCP 客户端配置示例：

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-gitlab/build/index.js"],//你的路径
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_PROJECT_ID": "123",
        "GITLAB_TOKEN": "your-gitlab-token"
      }
    }
  }
}

2. Streamable HTTP 模式

适用于开发和调试，支持 HTTP 端点访问：

# 使用原版实现（支持所有5个工具）
yarn dev

MCP 客户端配置示例：

{
  "mcpServers": {
    "gitlab-http": {
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_PROJECT_ID": "123",
        "GITLAB_TOKEN": "your-gitlab-token"
      },
      "url": "http://localhost:3300/mcp"
    }
  }
}

HTTP 端点：

• 🔗 MCP 端点: http://localhost:3300/mcp
• 💚 健康检查: http://localhost:3300/health
• 📋 服务信息: http://localhost:3300/

🔧 使用MCP Inspector调试

# 启动调试界面
./debug-with-inspector.sh

这将打开一个Web界面（通常在 http://localhost:5173），你可以在其中：

• 查看所有可用工具
• 测试工具调用
• 查看请求和响应
• 调试参数传递

🛠️ 核心功能

动态参数支持

所有工具都支持动态传入以下参数，无需预先配置：

• gitlabUrl: GitLab基础URL（如：https://gitlab.com）
• projectId: 项目ID或路径（如：123 或 group/project）
• token: GitLab访问令牌（如：glpat-xxxxxxxxxxxx）

可用工具列表

工具名称	功能描述	主要参数
trigger_pipeline	触发流水线	gitlabUrl, projectId, ref, token, variables(可选)
get_pipeline_status	获取流水线状态	gitlabUrl, projectId, pipelineId, token
list_pipelines	列出流水线	gitlabUrl, projectId, token, ref(可选), status(可选)
get_pipeline_jobs	获取流水线作业	gitlabUrl, projectId, pipelineId, token
cancel_pipeline	取消流水线	gitlabUrl, projectId, pipelineId, token

💬 使用示例

在支持MCP的AI客户端中，你可以使用自然语言来操作GitLab流水线：

基础操作

"帮我触发 mygroup/myproject 项目的 main 分支流水线，GitLab地址是 https://gitlab.example.com，使用令牌 glpat-xxxxxxxxxxxx"

"查看项目 123 在 https://gitlab.com 上的流水线 456 的状态"

"列出 mygroup/myproject 项目最近的流水线，只显示失败的"

高级操作

"触发流水线时传入环境变量 DEPLOY_ENV=production 和 VERSION=v1.2.3"

"取消正在运行的流水线 789"

"查看流水线 456 的所有作业状态，看看哪个作业失败了"

多环境支持

"在我们的私有GitLab https://gitlab.company.com 上触发项目 team/backend 的 develop 分支流水线"

"检查生产环境流水线状态，项目在 https://gitlab.com/prod/app，流水线ID是 999"

🔐 安全配置

GitLab访问令牌

1. 登录GitLab
2. 进入 Settings > Access Tokens
3. 创建新令牌，需要以下权限：
   • api - 完整API访问权限
   • read_repository - 读取仓库权限
   • write_repository - 写入仓库权限

环境变量安全

• 永远不要将 .env 文件提交到版本控制
• 使用不同的令牌用于不同的环境
• 定期轮换访问令牌
• 限制令牌的权限范围

📁 项目结构

mcp-gitlab/
├── src/                          # 源代码
│   ├── index.ts                  # 主服务器文件
│   ├── services/
│   │   └── gitlab.ts             # GitLab API服务
│   └── utils/
│       └── logger.ts             # 日志工具
├── dist/                         # 构建输出
├── .env.example                  # 环境变量模板
├── mcp-config-examples.json      # MCP客户端配置示例
├── test-server.js                # 服务器测试脚本
├── debug-with-inspector.sh       # 调试脚本
├── package.json                  # 项目配置
├── tsconfig.json                 # TypeScript配置
└── README.md                     # 项目说明

🐛 常见问题

Q: 服务器启动失败

A: 检查Node.js版本（需要>=18），确保依赖已安装，检查TypeScript编译错误。

Q: GitLab API调用失败

A: 验证访问令牌权限，检查GitLab URL格式，确认项目ID正确。

Q: MCP客户端连接不上

A: 检查配置文件路径，确认服务器已构建，查看客户端日志。

Q: 工具调用参数错误

A: 参考工具定义中的参数要求，使用MCP Inspector测试参数格式。

📚 相关资源

• Model Context Protocol 官方文档
• GitLab API 文档
• MCP TypeScript SDK