zhanggy/gitlab-mcp-server
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
8 Commits 1 Branch 0 Tags
81fe4ab2a02232f8c733eda3e310c29666b18634
T
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE

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+）
Reference in new issue View Git Blame Copy Permalink
S
Description
No description provided
Readme
116 KiB
0 Stars 1 Watchers 0 Forks
Languages
JavaScript 100%