gitlab-mcp-server/README.md

GitLab MCP Server

一个支持 GitLab 操作的 Model Context Protocol (MCP) 服务器，主要用于创建和管理 Merge Requests。

功能特性

• ✅ 创建 Merge Request
• ✅ 合并 Merge Request
• ✅ 获取 Merge Request 详情
• ✅ 关闭 Merge Request
• ✅ 快捷合并到测试分支
• ✅ 支持 Stdio 和 Streamable HTTP 两种传输方式
• ✅ 支持通过 npx 直接运行，无需安装

快速开始

方式一：使用 npx（推荐，无需安装）

# 1. 设置环境变量
export GITLAB_ACCESS_TOKEN="your_gitlab_token_here"

# 2. 直接运行（默认 stdio 模式）
npx gitlab-mcp-server

# 或使用 HTTP 模式
npx gitlab-mcp-server --transport http --port 3000

# 查看帮助
npx gitlab-mcp-server --help

方式二：本地安装运行

# 1. 克隆或下载项目
git clone <repository-url>
cd gitlab-mcp-server

# 2. 安装依赖
npm install

# 3. 设置环境变量
export GITLAB_ACCESS_TOKEN="your_gitlab_token_here"
export GITLAB_API_BASE_URL="https://gitlab.com/api/v4"  # 可选

# 4. 运行
npm start  # 默认 stdio 模式

环境变量配置

Windows (PowerShell)

# 临时设置（当前会话）
$env:GITLAB_ACCESS_TOKEN="your_token_here"
$env:GITLAB_API_BASE_URL="https://gitlab.com/api/v4"

# 永久设置（用户级别）
[System.Environment]::SetEnvironmentVariable('GITLAB_ACCESS_TOKEN', 'your_token_here', 'User')

Linux/Mac

# 临时设置
export GITLAB_ACCESS_TOKEN="your_token_here"
export GITLAB_API_BASE_URL="https://gitlab.com/api/v4"

# 永久设置（添加到 ~/.bashrc 或 ~/.zshrc）
echo 'export GITLAB_ACCESS_TOKEN="your_token_here"' >> ~/.bashrc
source ~/.bashrc

如何获取 GitLab Access Token

1. 登录 GitLab
2. 进入 Settings > Access Tokens
3. 创建新的 Personal Access Token
4. 选择 api 权限
5. 复制生成的 token

使用方式

通过 npx 运行（推荐）

# Stdio 模式（默认）
npx gitlab-mcp-server

# HTTP 模式
npx gitlab-mcp-server --transport http --port 3000

# 使用简写参数
npx gitlab-mcp-server -t http -p 8080

# 查看帮助
npx gitlab-mcp-server --help

本地运行

# 默认 stdio 模式
node index.js
npm start

# 明确指定 stdio 模式
node index.js --transport stdio
npm run start:stdio

# HTTP 模式
node index.js --transport http --port 3000
npm run start:http

# 开发模式（HTTP）
npm run dev:http

命令行参数

用法:
  node index.js [选项]

选项:
  -t, --transport <type>  传输方式: 'stdio' 或 'http' (默认: stdio)
  -p, --port <number>     HTTP 服务器端口 (默认: 3000, 仅在 http 模式下有效)
  -h, --help              显示帮助信息

示例:
  node index.js                              # stdio 模式
  node index.js --transport http --port 3000 # HTTP 模式
  npx gitlab-mcp-server -t http -p 8080      # HTTP 模式（使用 npx）

传输模式说明

Stdio 模式（默认）

通过标准输入/输出与客户端通信，这是 MCP 的标准传输方式。

适用场景：

• 与 Claude Desktop 或其他 MCP 客户端集成
• 作为子进程运行
• 本地开发和使用

特点：

• MCP 标准传输方式
• 低延迟
• 适合本地集成

Streamable HTTP 模式

使用最新的 Streamable HTTP 传输协议，支持远程访问和多客户端连接。

适用场景：

• 远程服务器部署
• 多客户端访问
• 调试和测试
• 需要 HTTP 接口的场景

特点：

• 基于 HTTP POST 的消息传输
• 支持 Server-Sent Events (SSE) 流式响应
• 支持断线重连和消息重放
• 更好的网络适应性

HTTP 端点：

• POST /message - MCP 消息端点（接收 JSON-RPC 请求，返回 JSON 或 SSE 流）

测试 HTTP 模式：

# 启动服务器
npm run start:http

# 在另一个终端发送测试请求
curl -X POST http://localhost:3000/message \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

在 MCP 客户端中使用

Claude Desktop 配置（使用 npx）

编辑 Claude Desktop 的配置文件：

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["gitlab-mcp-server"],
      "env": {
        "GITLAB_ACCESS_TOKEN": "your_token_here",
        "GITLAB_API_BASE_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

使用本地路径

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["d:/path/to/gitlab-mcp-server/index.js"],
      "env": {
        "GITLAB_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

HTTP 模式配置

如果你部署了 HTTP 模式的服务器，客户端可以通过 HTTP 连接：

{
  "mcpServers": {
    "gitlab-http": {
      "url": "http://localhost:3000/message",
      "transport": "streamable-http",
      "env": {
        "GITLAB_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

可用工具

1. create_merge_request

在指定的 GitLab 项目中创建一个新的 Merge Request。

参数:

• projectId (string): GitLab 项目的 ID 或 URL 编码的路径
• sourceBranch (string): 源分支名称
• targetBranch (string): 目标分支名称
• title (string): Merge Request 的标题
• description (string, 可选): Merge Request 的描述
• assigneeId (number, 可选): 负责人 ID
• reviewerIds (array, 可选): 审阅者 ID 数组

示例:

{
  "tool": "create_merge_request",
  "arguments": {
    "projectId": "123",
    "sourceBranch": "feature/new-feature",
    "targetBranch": "main",
    "title": "Add new feature",
    "description": "This PR adds a new feature",
    "assigneeId": 456,
    "reviewerIds": [789, 101]
  }
}

2. merge_merge_request

合并指定的 GitLab Merge Request。

参数:

• projectId (string): GitLab 项目的 ID 或 URL 编码的路径
• mrIid (number): Merge Request 的内部 ID
• mergeCommitMessage (string, 可选): 合并提交的消息
• shouldRemoveSourceBranch (boolean, 可选): 是否在合并后删除源分支
• mergeWhenPipelineSucceeds (boolean, 可选): 是否在 CI 管道成功后合并

示例:

{
  "tool": "merge_merge_request",
  "arguments": {
    "projectId": "123",
    "mrIid": 42,
    "mergeCommitMessage": "Merge feature branch",
    "shouldRemoveSourceBranch": true,
    "mergeWhenPipelineSucceeds": false
  }
}

3. get_merge_request

获取指定 Merge Request 的详细信息。

参数:

• projectId (string): GitLab 项目的 ID 或 URL 编码的路径
• mrIid (number): Merge Request 的内部 ID

示例:

{
  "tool": "get_merge_request",
  "arguments": {
    "projectId": "123",
    "mrIid": 42
  }
}

4. close_merge_request

关闭指定的 GitLab Merge Request 而不合并。

参数:

• projectId (string): GitLab 项目的 ID 或 URL 编码的路径
• mrIid (number): Merge Request 的内部 ID

示例:

{
  "tool": "close_merge_request",
  "arguments": {
    "projectId": "123",
    "mrIid": 42
  }
}

5. merge_to_test

快捷工具：将源分支合并到测试分支（test）并自动部署。

参数:

• projectId (string): GitLab 项目的 ID
• sourceBranch (string): 源分支名称（如果未提供，将自动获取当前分支）

示例:

{
  "tool": "merge_to_test",
  "arguments": {
    "projectId": "123",
    "sourceBranch": "feature/my-feature"
  }
}

常见问题

Q: 如何找到项目 ID?

A:

1. 进入 GitLab 项目页面
2. 项目 ID 显示在项目名称下方
3. 或者使用项目的 URL 编码路径，如 username%2Fproject-name

Q: Stdio 和 HTTP 模式有什么区别?

A:

• Stdio 模式: 通过标准输入/输出通信，MCP 标准方式，适合本地集成
• HTTP 模式: 使用 Streamable HTTP 协议，适合远程访问、多客户端和调试

Q: 什么是 Streamable HTTP?

A: Streamable HTTP 是 MCP 的最新 HTTP 传输协议，相比旧的 SSE 传输有以下优势：

• 统一的连接模型（单个 POST 请求即可发送和接收）
• 支持断线重连和消息重放
• 更好的网络适应性
• 更高的可靠性

Q: 端口被占用怎么办？

A: 使用不同的端口：

node index.js --transport http --port 8080

Q: 如何查看详细日志？

A: 日志输出到 stderr，可以重定向到文件：

node index.js --transport http 2> server.log

Q: npx 和本地安装有什么区别？

A:

• npx: 无需安装，直接运行最新版本，适合快速测试和使用
• 本地安装: 需要先安装依赖，但可以离线使用，适合开发和定制

开发

使用 MCP Inspector 调试

# Stdio 模式
npm run dev

# HTTP 模式
npm run dev:http

MCP Inspector 会启动一个交互式界面，让你可以测试服务器的各项功能。

项目结构

gitlab-mcp-server/
├── index.js           # 主入口文件
├── package.json       # 项目配置
├── README.md          # 文档
├── .npmignore         # npm 发布配置
└── .gitignore         # Git 忽略配置

发布到 npm

如果你想发布自己的版本到 npm：

# 1. 登录 npm
npm login

# 2. 更新版本号
npm version patch  # 或 minor, major

# 3. 发布
npm publish

# 4. 发布后，其他人可以通过 npx 使用
npx your-package-name

技术栈

• @modelcontextprotocol/sdk: MCP SDK (最新版本，支持 Streamable HTTP)
• zod: 参数验证
• Node.js: 运行时环境

更新日志

[1.1.0] - 2025-12-15

新增功能:

• ✨ 支持通过命令行参数选择传输方式（stdio 或 http）
• ✨ 使用最新的 Streamable HTTP 传输协议（替代已弃用的 SSE）
• ✨ 支持通过 npx 直接运行，无需安装
• ✨ 添加 bin 字段，支持 gitlab-mcp-server 和 gitlab-mcp 命令
• ✨ 添加命令行帮助信息 --help

改进:

• 📝 完善文档，整合所有内容到 README
• 🔧 默认使用 stdio 模式（MCP 标准）
• 🔧 升级 SDK 到最新版本，移除已弃用的 API
• 🔧 优化服务器启动逻辑，支持参数化配置

技术细节:

• 使用 StreamableHTTPServerTransport 替代已弃用的 SSEServerTransport
• 升级 @modelcontextprotocol/sdk 到最新版本（1.24.0+）
• 添加 DNS rebinding 保护（SDK 1.24.0 的安全特性）

[1.0.0] - 初始版本

功能:

• ✅ 创建 Merge Request
• ✅ 合并 Merge Request
• ✅ 获取 Merge Request 详情
• ✅ 关闭 Merge Request
• ✅ 快捷合并到测试分支

许可证

ISC

作者

Jasery

贡献

欢迎提交 Issue 和 Pull Request！

支持

如果遇到问题，请检查：

1. ✅ 环境变量 GITLAB_ACCESS_TOKEN 是否正确设置
2. ✅ GitLab API 是否可访问
3. ✅ Token 是否有足够的权限（需要 api 权限）
4. ✅ 项目 ID 是否正确
5. ✅ 使用的 SDK 版本是否为最新版本（1.24.0+）