gitlab-mcp-server

cyphbt/gitlab-mcp-server

3.1

If you are the rightful owner of gitlab-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

This is a GitLab Model Context Protocol (MCP) server that provides functionalities for managing GitLab projects.

GitLab MCP 服务器

这是一个 GitLab 的 Model Context Protocol (MCP) 服务器，提供了三个主要功能：

  1. 查询最新标签 - 获取项目的最新标签列表
  2. 创建标签 - 创建新的标签（支持描述信息）
  3. 创建合并请求 - 提交新的合并请求

功能特性

1. 自动检测项目信息 (gitlab_get_project_info)

  • 自动检测当前 Git 仓库的 GitLab 项目信息
  • 显示项目名称、描述、可见性等基本信息
  • 显示当前分支和 Git 配置信息
  • 显示最近的提交历史

2. 查询最新标签 (gitlab_get_latest_tags)

  • 获取项目的最新标签列表
  • 支持限制返回数量
  • 按版本号排序（降序）

3. 创建标签 (gitlab_create_tag)

  • 创建新的 Git 标签
  • 支持标签消息和发布描述
  • 可以指向任意分支或提交

4. 创建合并请求 (gitlab_create_merge_request)

  • 创建新的合并请求
  • 支持详细的描述信息
  • 可配置是否删除源分支和压缩提交

5. 智能自动检测

  • 零配置: 只需要设置 GitLab Token 或使用 SSH 模式
  • 自动解析: 从 Git 远程仓库自动解析 GitLab URL 和项目路径
  • 动态获取: 通过 API 自动获取项目 ID
  • 实时状态: 自动获取当前分支和项目状态

6. 双模式支持

  • Token 模式: 使用 GitLab API，功能完整
  • SSH 模式: 使用 Git 命令和 GitLab CLI，无需 Token

安装和配置

方式 1: npm 安装（推荐）

全局安装
npm install -g @cyphbt/gitlab-mcp-server
本地安装
npm install @cyphbt/gitlab-mcp-server

方式 2: 从源码安装

# 克隆仓库
git clone https://github.com/yourusername/gitlab-mcp-server.git
cd gitlab-mcp-server

# 安装依赖
npm install

# 构建项目
npm run build

配置环境变量

Token 模式

复制 env.example 文件为 .env 并填写你的 GitLab Token：

cp env.example .env

编辑 .env 文件：

# GitLab 配置
GITLAB_TOKEN=your_gitlab_personal_access_token
SSH 模式

如果你选择 SSH 模式，无需设置 Token，但需要安装 GitLab CLI：

# 安装 GitLab CLI
./install-glab.sh

# 验证 SSH 连接
git ls-remote origin

注意: 这个工具会自动检测当前 Git 仓库的 GitLab 项目信息。

配置方式选择

方式 1: Token 模式（推荐）
  1. 登录你的 GitLab 账户
  2. 进入 Settings > Access Tokens
  3. 创建一个新的 Personal Access Token
  4. 确保勾选以下权限：
    • api - 完整的 API 访问权限
    • read_repository - 读取仓库
    • write_repository - 写入仓库
方式 2: SSH 模式（无需 Token）

如果你已经有 SSH 密钥配置，可以选择 SSH 模式：

  1. 安装 GitLab CLI：

    ./install-glab.sh

  2. 验证 SSH 连接：

    git ls-remote origin

  3. 不设置 GITLAB_TOKEN 环境变量，工具会自动使用 SSH 模式

4. 自动检测功能

这个 MCP 工具会自动检测：

  • GitLab URL: 从 Git 远程仓库 URL 自动解析
  • 项目 ID: 通过 GitLab API 自动获取（Token 模式）或使用项目路径（SSH 模式）
  • 当前分支: 从 Git 仓库状态自动获取
  • 项目信息: 包括项目名称、描述、可见性等

支持以下 Git 远程 URL 格式：

  • HTTPS: https://gitlab.com/group/project.git
  • SSH: git@gitlab.com:group/project.git

5. 构建项目

npm run build

使用方法

启动服务器

npm 安装后
# 全局安装
gitlab-mcp

# 本地安装
npx @cyphbt/gitlab-mcp-server
源码安装后
npm start

在 Cursor 中配置

  1. 打开 Cursor
  2. 进入 Settings > Extensions > Model Context Protocol
  3. 添加新的 MCP 服务器配置：
全局安装后
{
  "mcpServers": {
    "gitlab": {
      "command": "gitlab-mcp",
      "env": {
        "GITLAB_TOKEN": "your_token"
      }
    }
  }
}
本地安装后
{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["@cyphbt/gitlab-mcp-server"],
      "env": {
        "GITLAB_TOKEN": "your_token"
      }
    }
  }
}
源码安装后
{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/path/to/your/gitlab-mcp-server/dist/index.js"],
      "env": {
        "GITLAB_TOKEN": "your_token"
      }
    }
  }
}

注意: SSH 模式下无需设置 GITLAB_TOKEN，其他信息会自动从当前 Git 仓库检测。

在其他 MCP 客户端中使用

根据你的 MCP 客户端，配置方式可能略有不同，但基本结构是相同的：

{
  "command": "gitlab-mcp",
  "env": {
    "GITLAB_TOKEN": "your_token"
  }
}

API 使用示例

查询最新标签

{
  "name": "gitlab_get_latest_tags",
  "arguments": {
    "limit": 5
  }
}

创建标签

{
  "name": "gitlab_create_tag",
  "arguments": {
    "tag_name": "v1.2.0",
    "ref": "main",
    "message": "Release version 1.2.0",
    "release_description": "This release includes bug fixes and performance improvements."
  }
}

创建合并请求

{
  "name": "gitlab_create_merge_request",
  "arguments": {
    "source_branch": "feature/new-feature",
    "target_branch": "main",
    "title": "Add new feature",
    "description": "This merge request adds a new feature that improves user experience.",
    "remove_source_branch": true,
    "squash": false
  }
}

开发

开发模式运行

npm run dev

构建项目

npm run build

错误处理

服务器会处理各种错误情况：

  • 配置错误（缺少必要的环境变量）
  • GitLab API 错误
  • 网络连接错误
  • 权限错误

所有错误都会以用户友好的中文消息返回。

安全注意事项

  1. Token 安全: 确保你的 GitLab Personal Access Token 安全存储，不要提交到版本控制系统
  2. 权限最小化: 只给 Token 必要的权限
  3. 环境变量: 使用 .env 文件存储敏感信息，确保该文件被 .gitignore 忽略

故障排除

常见问题

  1. "未设置 GITLAB_TOKEN 环境变量"

    • 确保在 .env 文件中设置了 GITLAB_TOKEN

  2. "未设置 GITLAB_PROJECT_ID 环境变量"

    • 确保在 .env 文件中设置了正确的项目 ID

  3. "获取标签失败: 401 Unauthorized"

    • 检查你的 GitLab Token 是否有效
    • 确保 Token 有足够的权限

  4. "获取标签失败: 404 Not Found"

    • 检查项目 ID 是否正确
    • 确保你有访问该项目的权限

许可证

MIT License # gitlab-mcp-server