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访问令牌

登录GitLab
进入 Settings > Access Tokens
创建新令牌，需要以下权限：
- 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测试参数格式。

📚 相关资源

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables AI clients to manage GitLab pipelines through natural language commands. Supports triggering pipelines, checking status, listing pipelines, viewing jobs, and canceling pipelines across multiple GitLab instances.

Related MCP Servers

GitLab MCP Server
chris-miaskowski
-
security
F
license
-
quality
A custom server implementation that allows AI assistants to interact with GitLab repositories, providing capabilities for searching, fetching files, creating/updating content, and managing issues and merge requests.
Last updated -
1
JavaScript
GitHub MCP Server
tuanle96
A
security
F
license
A
quality
Enables comprehensive GitHub operations through natural language including file management, repository administration, issue tracking, and advanced code searching.
Last updated -
47
1
1
TypeScript
GitLab MCP Server
lucky-dersan
-
security
F
license
-
quality
Provides GitLab integration for AI assistants using Model Context Protocol, enabling repository operations, file management, issue tracking, merge requests, and branch/tag administration through natural language.
Last updated -
2
Python
GitLab MCP Server
amirsina-mandegari
-
security
F
license
-
quality
Connects AI assistants to GitLab, allowing users to manage merge requests, view reviews, and interact with discussions through natural language queries.
Last updated -
8
Python

View all related MCP servers

GitLab Pipeline MCP Server