mcp-gitlab MCP Server (English)

中文版

mcp-gitlab MCP 服务（英文）

基于 fastmcp 框架构建的 GitLab 集成服务，提供各种 GitLab RESTful API 工具。支持与 Claude、Smithery 和其他平台集成。

功能

• GitlabSearchUserProjectsTool：按用户名搜索用户及其活跃项目
• GitlabGetUserTasksTool：获取当前用户的待处理任务
• GitlabSearchProjectDetailsTool：搜索项目及其详情
• GitlabCreateMRCommentTool：为合并请求添加评论
• GitlabAcceptMRTool：接受并合并合并请求
• GitlabUpdateMRTool：更新合并请求的受派人、审核者、标题、描述和标签
• GitlabCreateMRTool：创建带受派人和审核者的新合并请求
• GitlabRawApiTool：使用自定义参数调用任意 GitLab API

快速开始

Stdio 模式（默认）

# Install dependencies
bun install

# Build the project
bun run build

# Start the server with stdio transport (default)
bun run start

HTTP Stream 模式（服务部署）

# Install dependencies
bun install

# Build the project
bun run build

# Start the server with HTTP stream transport
MCP_TRANSPORT_TYPE=httpStream MCP_PORT=3000 bun run start

# Or using command line flag
bun dist/index.js --http-stream

环境变量

# Required for all modes (optional for httpStream mode - can be provided via HTTP headers)
GITLAB_API_URL=https://your-gitlab-instance.com

# Required for stdio mode, optional for httpStream mode
# (can be provided via HTTP headers in httpStream mode)
GITLAB_TOKEN=your_access_token

# Optional: Provide a mapping from usernames to user IDs (JSON string)
# This can reduce API calls, especially when referencing the same users frequently
# Example: '{"username1": 123, "username2": 456}'
GITLAB_USER_MAPPING={"username1": 123, "username2": 456}

# Optional: Provide a mapping from project names to project IDs (JSON string)
# Project IDs can be numbers or strings (e.g., 'group/project')
# This can reduce API calls and ensure the correct project is used
# Example: '{"project-name-a": 1001, "group/project-b": "group/project-b"}'
GITLAB_PROJECT_MAPPING={"project-name-a": 1001, "group/project-b": "group/project-b"}

# MCP Transport Configuration (Optional)
# Transport type: stdio (default) or httpStream  
MCP_TRANSPORT_TYPE=stdio

# HTTP Stream Configuration (Only used when MCP_TRANSPORT_TYPE=httpStream)
# Server binding address (default: 0.0.0.0 for httpStream, localhost for stdio)
# For Docker deployments, use 0.0.0.0 to allow external access
MCP_HOST=0.0.0.0

# Server port (default: 3000)
MCP_PORT=3000

# API endpoint path (default: /mcp)
MCP_ENDPOINT=/mcp

使用示例

直接使用 HTTP API

你也可以通过 HTTP 请求直接与 MCP 服务交互：

# Example: Get user tasks using 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"]
      }
    }
  }'

# Example: Search projects using PRIVATE-TOKEN header
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"]
      }
    }
  }'

# Example: Use dynamic GitLab instance URL with 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 Stream 模式结合动态身份验证的主要优势：

• 多租户支持：单个服务实例可为多个用户提供服务
• 安全性：每个请求都使用自己的身份验证令牌和 GitLab 实例 URL
• 灵活性：可为每个客户端配置令牌和 GitLab URL，无需重启服务
• 多实例支持：从同一服务连接到不同的 GitLab 实例

传输模式

此服务支持两种传输模式：

1. Stdio 传输（默认）

• 最适合本地开发以及与 MCP 客户端直接集成
• 使用 stdin/stdout 进行通信
• 无需网络配置

2. HTTP Stream 传输

• 支持部署服务以供远程访问
• 使用带流式响应的 HTTP POST 请求
• 允许多个客户端连接到同一服务实例
• 非常适合生产部署
• 支持通过 HTTP 标头进行动态令牌身份验证

使用 HTTP Stream 模式时，客户端可以连接到：

POST http://localhost:3000/mcp
Content-Type: application/json

身份验证方法

HTTP Stream 模式支持多种方式来提供 GitLab 令牌和实例 URL：

令牌身份验证：

1. Bearer 令牌（推荐）：

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 server entry point
├── 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 config
USAGE.md                          # Usage examples
package.json
tsconfig.json

集成

Claude 桌面客户端

Stdio 模式（默认）

添加到你的配置中：

{
  "mcpServers": {
    "@zephyr-mcp/gitlab": {
      "command": "npx",
      "args": ["-y", "@zephyr-mcp/gitlab"]
    }
  }
}

HTTP Stream 模式（服务器部署）

服务器设置： 首先启动服务器（请注意，使用 HTTP 标头时，GITLAB_TOKEN 和 GITLAB_API_URL 均为可选项）：

# On your server - no token or URL required in env vars
MCP_TRANSPORT_TYPE=httpStream MCP_PORT=3000 MCP_HOST=0.0.0.0 npx @zephyr-mcp/gitlab

# Or with 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"
      ]
    }
  }
}

多租户用法： 每位用户都可以在自己的客户端配置中设置专属 Token 和 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_HOST：HTTP Stream 模式下的服务器绑定地址
• MCP_PORT：HTTP Stream 模式下的 HTTP 端口
• MCP_ENDPOINT：HTTP Stream 模式下的 HTTP 端点路径

部署

Docker 部署

仓库中包含 Dockerfile，便于部署：

# Build the Docker image
docker build -t gitlab-mcp-server .

# Run with environment variables (both token and URL can be provided via HTTP headers)
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
      # Both GITLAB_API_URL and GITLAB_TOKEN are optional when using HTTP headers
      # - GITLAB_API_URL=https://your-gitlab-instance.com
      # - GITLAB_TOKEN=your_gitlab_token
    command: npx -y @zephyr-mcp/gitlab@latest

**Docker 重要提示：**在 Docker 容器中运行时，请务必设置 MCP_HOST=0.0.0.0，以允许外部访问。httpStream 传输的默认值已经是 0.0.0.0，但显式设置可确保兼容性。

手动部署

# Install dependencies and build
npm install
npm run build

# Start the server in HTTP stream mode
export GITLAB_API_URL=https://your-gitlab-instance.com
export GITLAB_TOKEN=your_access_token
export MCP_TRANSPORT_TYPE=httpStream
export MCP_PORT=3000

# Run the server
node dist/index.js

进程管理器（PM2）

# Install PM2
npm install -g pm2

# Create ecosystem file
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

# Start with PM2
pm2 start ecosystem.config.js
pm2 save
pm2 startup

相关链接

• fastmcp
• Smithery
• GitLab API