MCP服务器-GitLab
项目介绍
技术文档摘要
mcp-gitlab MCP 服务器（英文）
基于 fastmcp 框架构建的 GitLab 集成服务器，提供各种 GitLab RESTful API 工具。支持与 Claude、Smithery 等平台集成。
功能
- GitlabSearchUserProjectsTool通过用户名搜索用户及其活跃项目
- GitlabGetUserTasksTool获取当前用户的待办任务
- GitlabSearchProjectDetailsTool搜索项目及详细信息
- GitlabCreateMRCommentTool向合并请求添加评论
- GitlabAcceptMRTool接受并合并合并请求
- GitlabUpdateMRTool更新合并请求分配人、审阅人、标题、描述和标签
- GitlabCreateMRTool创建新的合并请求，并指定分配人和审阅人
- GitlabRawApiTool使用自定义参数调用任何 GitLab API
快速开始
标准 I/O 模式（默认）
# 安装依赖
bun install
# 构建项目
bun run build
# 使用标准 I/O 传输启动服务器（默认）
bun run start
HTTP 流模式（服务器部署）
# 安装依赖
bun install
# 构建项目
bun run build
# 使用 HTTP 流传输启动服务器
MCP_TRANSPORT_TYPE=httpStream MCP_PORT=3000 bun run start
# 或使用命令行标志
bun dist/index.js --http-stream
环境变量
# 所有模式都需要（对于 httpStream 模式可选，可通过 HTTP 头提供）
GITLAB_API_URL=https://your-gitlab-instance.com
# 标准 I/O 模式需要，httpStream 模式可选
# （在 httpStream 模式下可通过 HTTP 头提供）
GITLAB_TOKEN=your_access_token
# 可选：提供用户名到用户 ID 的映射（JSON 字符串）
# 这可以减少 API 调用，特别是在频繁引用相同用户时
# 示例：'{"username1": 123, "username2": 456}'
GITLAB_USER_MAPPING={"username1": 123, "username2": 456}
# 可选：提供项目名到项目 ID 的映射（JSON 字符串）
# 项目 ID 可以是数字或字符串（例如，'group/project'）
# 这可以减少 API 调用并确保使用正确的项目
# 示例：'{"project-name-a": 1001, "group/project-b": "group/project-b"}'
GITLAB_PROJECT_MAPPING={"project-name-a": 1001, "group/project-b": "group/project-b"}
# MCP 传输配置（可选）
# 传输类型：stdio（默认）或 httpStream
MCP_TRANSPORT_TYPE=stdio
# HTTP 流配置（仅当 MCP_TRANSPORT_TYPE=httpStream 时使用）
# 服务器绑定地址（默认：httpStream 为 0.0.0.0，stdio 为 localhost）
# 对于 Docker 部署，使用 0.0.0.0 允许外部访问
MCP_HOST=0.0.0.0
# 服务器端口（默认：3000）
MCP_PORT=3000
# API 端点路径（默认：/mcp）
MCP_ENDPOINT=/mcp
使用示例
直接 HTTP API 使用
您也可以通过 HTTP 请求直接与 MCP 服务器交互：
# 示例：使用 Bearer token 获取用户任务
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-gitlab-token" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "Gitlab Get User Tasks Tool",
"arguments": {
"taskFilterType": "ASSIGNED_MRS",
"fields": ["id", "title", "source_branch", "target_branch"]
}
}
}'
# 示例：使用 PRIVATE-TOKEN 头搜索项目
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "PRIVATE-TOKEN: your-gitlab-token" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "Gitlab Search Project Details Tool",
"arguments": {
"projectName": "my-project",
"fields": ["id", "name", "description", "web_url"]
}
}
}'
# 示例：使用动态 GitLab 实例 URL 和 Bearer token
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-gitlab-token" \
-H "x-gitlab-url: https://gitlab.company.com" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "Gitlab Get User Tasks Tool",
"arguments": {
"taskFilterType": "ASSIGNED_MRS",
"fields": ["id", "title", "source_branch", "target_branch"]
}
}
}'
工具示例
每个工具参数的详细示例，请参见 USAGE.md。
HTTP 流模式下的动态认证的主要优点：
- 多租户支持单个服务器实例可以服务于多个用户。
- 安全性每次请求都使用自己的认证令牌和 GitLab 实例 URL。
- 灵活性令牌和 GitLab URL 可以按客户端配置，无需重启服务器。
- 多实例支持从同一服务器连接不同的 GitLab 实例。
传输模式
此服务器支持两种传输模式：
1. 标准 I/O 传输（默认）
- 最适合本地开发和直接与 MCP 客户端集成。
- 使用标准输入/输出进行通信。
- 不需要网络配置。
2. HTTP 流传输
- 启用远程访问的服务器部署。
- 使用 HTTP POST 请求和流响应。
- 允许多个客户端连接到同一个服务器实例。
- 适用于生产部署。
- 支持通过 HTTP 头进行动态令牌认证
使用 HTTP 流模式时，客户端可以连接到：
POST http://localhost:3000/mcp
Content-Type: application/json
认证方法
HTTP 流模式支持多种方式提供 GitLab 令牌和实例 URL：
令牌认证：
1. Bearer Token（推荐）：
POST http://localhost:3000/mcp
Content-Type: application/json
Authorization: Bearer your-gitlab-access-token
2. Private Token 头：
POST http://localhost:3000/mcp
Content-Type: application/json
PRIVATE-TOKEN: your-gitlab-access-token
3. 替代 Private Token 头：
POST http://localhost:3000/mcp
Content-Type: application/json
private-token: your-gitlab-access-token
4. 自定义 GitLab Token 头：
POST http://localhost:3000/mcp
Content-Type: application/json
x-gitlab-token: your-gitlab-access-token
GitLab 实例 URL 配置：
1. GitLab URL 头（推荐）：
POST http://localhost:3000/mcp
Content-Type: application/json
x-gitlab-url: https://gitlab.company.com
2. 替代 GitLab URL 头：
POST http://localhost:3000/mcp
Content-Type: application/json
gitlab-url: https://gitlab.company.com
POST http://localhost:3000/mcp
Content-Type: application/json
gitlab-api-url: https://gitlab.company.com
5. 回退到环境变量：
如果未在头中提供令牌或 URL，服务器将回退到 GITLAB_TOKEN 和 GITLAB_API_URL 环境变量。
完整示例：
POST http://localhost:3000/mcp
Content-Type: application/json
Authorization: Bearer your-gitlab-access-token
x-gitlab-url: https://gitlab.company.com
项目结构
src/
├── server/
│ └── GitlabMCPServer.ts # MCP 服务器入口点
├── tools/
│ ├── GitlabAcceptMRTool.ts
│ ├── GitlabCreateMRCommentTool.ts
│ ├── GitlabGetUserTasksTool.ts
│ ├── GitlabRawApiTool.ts
│ ├── GitlabSearchProjectDetailsTool.ts
│ ├── GitlabSearchUserProjectsTool.ts
│ └── gitlab/
│ ├── FieldFilterUtils.ts
│ ├── GitlabApiClient.ts
│ └── GitlabApiTypes.ts
├── utils/
│ ├── is.ts
│ └── sensitive.ts
smithery.json # Smithery 配置
USAGE.md # 使用示例
package.json
tsconfig.json
集成
Claude 桌面客户端
标准 I/O 模式（默认）
添加到您的配置：
{
"mcpServers": {
"@zephyr-mcp/gitlab": {
"command": "npx",
"args": ["-y", "@zephyr-mcp/gitlab"]
}
}
}
HTTP 流模式（服务器部署）
服务器设置：
首先启动服务器（注意，当使用 HTTP 头时，GITLAB_TOKEN 和 GITLAB_API_URL 是可选的）：
# 在您的服务器上 - 环境变量中不需要 token 或 URL
MCP_TRANSPORT_TYPE=httpStream MCP_PORT=3000 MCP_HOST=0.0.0.0 npx @zephyr-mcp/gitlab
# 或使用 Docker
docker run -d \
-p 3000:3000 \
-e MCP_TRANSPORT_TYPE=httpStream \
-e MCP_HOST=0.0.0.0 \
-e MCP_PORT=3000 \
gitlab-mcp-server
客户端配置：
选项 1：使用 Bearer Token（推荐）
{
"mcpServers": {
"@zephyr-mcp/gitlab": {
"command": "npx",
"args": [
"@modelcontextprotocol/client-cli",
"http://your-server:3000/mcp",
"--header", "Authorization: Bearer your-gitlab-access-token"
]
}
}
}
选项 2：使用 Private Token 头
{
"mcpServers": {
"@zephyr-mcp/gitlab": {
"command": "npx",
"args": [
"@modelcontextprotocol/client-cli",
"http://your-server:3000/mcp",
"--header", "PRIVATE-TOKEN: your-gitlab-access-token"
]
}
}
}
选项 3：使用动态 GitLab URL 和 Token
{
"mcpServers": {
"@zephyr-mcp/gitlab": {
"command": "npx",
"args": [
"@modelcontextprotocol/client-cli",
"http://your-server:3000/mcp",
"--header", "Authorization: Bearer your-gitlab-access-token",
"--header", "x-gitlab-url: https://gitlab.company.com"
]
}
}
}
多租户使用： 每个用户可以在其客户端设置中配置自己的令牌和 GitLab 实例 URL，使同一个服务器实例能够服务于具有不同 GitLab 权限和实例的多个用户。
Smithery
直接在 Smithery 平台上使用：
smithery add @zephyr-mcp/gitlab
或在 Smithery UI 中搜索 "@zephyr-mcp/gitlab" 并将其添加到您的工作区。
环境变量：
GITLAB_API_URL您的 GitLab API 的基础 URL（stdio 模式下必需，httpStream 模式下可选 - 可通过 HTTP 头提供）GITLAB_TOKEN用于 GitLab API 认证的访问令牌（stdio 模式下必需，httpStream 模式下可选 - 可通过 HTTP 头提供）MCP_TRANSPORT_TYPE传输类型（stdio/httpStream）MCP_HOSTHTTP 流模式下的服务器绑定地址MCP_PORTHTTP 流模式下的 HTTP 端口MCP_ENDPOINTHTTP 流模式下的 HTTP 端点路径
部署
Docker 部署
仓库包含一个 Dockerfile，便于部署：
# 构建 Docker 镜像
docker build -t gitlab-mcp-server .
# 运行并设置环境变量（令牌和 URL 可通过 HTTP 头提供）
docker run -d \
-p 3000:3000 \
-e MCP_TRANSPORT_TYPE=httpStream \
-e MCP_HOST=0.0.0.0 \
-e MCP_PORT=3000 \
gitlab-mcp-server
Docker Compose 示例
services:
gitlab-mcp:
image: node:22.14.0
container_name: gitlab-mcp
ports:
- "3000:3000"
environment:
- MCP_TRANSPORT_TYPE=httpStream
- MCP_HOST=0.0.0.0
- MCP_PORT=3000
# 当使用 HTTP 头时，GITLAB_API_URL 和 GITLAB_TOKEN 是可选的
# - GITLAB_API_URL=https://your-gitlab-instance.com
# - GITLAB_TOKEN=your_gitlab_token
command: npx -y @zephyr-mcp/gitlab@latest
重要提示： 在 Docker 容器中运行时，请确保设置 MCP_HOST=0.0.0.0 以允许外部访问。httpStream 传输的默认值已经是 0.0.0.0，但显式设置确保兼容性。
手动部署
# 安装依赖并构建
npm install
npm run build
# 在 HTTP 流模式下启动服务器
export GITLAB_API_URL=https://your-gitlab-instance.com
export GITLAB_TOKEN=your_access_token
export MCP_TRANSPORT_TYPE=httpStream
export MCP_PORT=3000
# 运行服务器
node dist/index.js
进程管理器（PM2）
# 安装 PM2
npm install -g pm2
# 创建生态系统文件
cat > ecosystem.config.js << EOF
module.exports = {
apps: [{
name: 'gitlab-mcp-server',
script: 'dist/index.js',
env: {
GITLAB_API_URL: 'https://your-gitlab-instance.com',
GITLAB_TOKEN: 'your_access_token',
MCP_TRANSPORT_TYPE: 'httpStream',
MCP_PORT: 3000
}
}]
}
EOF
# 使用 PM2 启动
pm2 start ecosystem.config.js
pm2 save
pm2 startup