npm package: @shencom/gitlab-mcp
Description: GitLab MCP Server for Cursor and Claude Code - stdio transport
Author: shencom
Latest version: 1.0.1

# GitLab MCP Server

基于 MCP (Model Context Protocol) 的 GitLab 集成服务，支持 **Cursor** 和 **Claude Code**，通过 stdio 传输方式通信。

## 功能特性

### 读操作
- 项目搜索（在可见范围内）
- 获取 MR 基础信息和 diff（用于总结与评审）
- 读取 pipeline / job 状态

### 写操作
- 创建分支（ref 默认 master）
- 创建 MR、创建 issue
- 触发 pipeline
- 创建 MR 行内评论（discussion thread）

### 高危操作（需二次确认）
- 删除分支（禁止删除 master/默认分支）

## 安装

```bash
# 全局安装（推荐）
npm install -g @shencom/gitlab-mcp

# 或使用 npx 直接运行
npx @shencom/gitlab-mcp
```

## 配置

### 1. 环境变量

| 变量              | 必填 | 说明                                             |
| ----------------- | ---- | ------------------------------------------------ |
| `GITLAB_BASE_URL` | 是   | GitLab 实例地址，如 `https://gitlab.example.com` |
| `GITLAB_TOKEN`    | 是   | Personal Access Token (scope=api)                |
| `DEFAULT_BRANCH`  | 否   | 默认分支，默认 `master`                          |
| `CONFIRM_TTL_SEC` | 否   | 确认码有效期（秒），默认 60                      |
| `DENY_PROJECTS`   | 否   | 项目黑名单，逗号分隔                             |

### 2. 获取 GitLab Token

1. 登录 GitLab（如 https://gitlab.example.com）
2. 进入 **Settings** → **Access Tokens**
3. 创建新 Token，勾选 **api** scope
4. 复制生成的 Token（格式如 `glpat-xxxxxxxxxxxx`）

### 3. 配置 MCP

#### 3.1 Cursor 配置

打开 Cursor 设置文件 `~/.cursor/mcp.json`（如不存在则创建）：

**方式一：使用 npx**

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@shencom/gitlab-mcp"],
      "env": {
        "GITLAB_BASE_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxx",
        "DEFAULT_BRANCH": "master",
        "CONFIRM_TTL_SEC": "60"
      }
    }
  }
}
```

#### 3.2 Claude Code 配置

编辑 Claude Code 的 MCP 配置文件 `~/.claude.json`：

```json
{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@shencom/gitlab-mcp"],
      "env": {
        "GITLAB_BASE_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxx",
        "DEFAULT_BRANCH": "master",
        "CONFIRM_TTL_SEC": "60"
      }
    }
  }
}
```

或者使用 Claude Code CLI 添加：

```bash
# 添加 MCP 服务器
claude mcp add gitlab -e GITLAB_BASE_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxx -- npx -y @shencom/gitlab-mcp
```
 

> **注意**：将 `GITLAB_TOKEN` 替换为你的 Token，本地路径方式需要将路径替换为实际的项目路径。

### 4. 配置 Skills（可选）

本包提供了 Agent Skill 配置，帮助 AI 更好地使用 GitLab MCP 工具。

#### Cursor Skills

将 `skills/SKILL.md` 复制到你的项目或全局 skills 目录：

```bash
# 项目级别
mkdir -p .claude/skills/gitlab-mcp
cp $(npm root -g)/@shencom/gitlab-mcp/skills/SKILL.md .claude/skills/gitlab-mcp/

# 或全局级别
mkdir -p ~/.claude/skills/gitlab-mcp
cp $(npm root -g)/@shencom/gitlab-mcp/skills/SKILL.md ~/.claude/skills/gitlab-mcp/
```

#### Claude Code Skills

Claude Code 也支持 skills，配置方式相同：

```bash
mkdir -p ~/.claude/skills/gitlab-mcp
cp $(npm root -g)/@shencom/gitlab-mcp/skills/SKILL.md ~/.claude/skills/gitlab-mcp/
```

### 5. 重启 IDE

配置完成后，重启 Cursor 或 Claude Code 使 MCP 配置生效。

## 开发调试

使用 MCP Inspector 进行调试：

```bash
# 克隆项目
git clone <repo-url>
cd gitlab-mcp

# 安装依赖
pnpm install

# 1. 创建 .env 文件
cp env.template .env
# 编辑 .env 填写 GITLAB_TOKEN

# 2. 启动 Inspector
pnpm inspector
```

Inspector 会自动读取 `.env` 文件并通过 `-e` 参数传递环境变量给 MCP Server。

## 可用 Tools

| Tool                           | 说明                 |
| ------------------------------ | -------------------- |
| `search_projects`              | 搜索项目             |
| `list_mrs`                     | 列出 MR              |
| `get_mr_changes`               | 获取 MR diff         |
| `create_branch`                | 创建分支             |
| `create_mr`                    | 创建 MR              |
| `merge_mr`                     | 合并 MR              |
| `create_issue`                 | 创建 Issue           |
| `run_pipeline`                 | 触发 Pipeline        |
| `create_mr_discussion_newline` | 创建 MR 行内评论     |
| `reply_mr_discussion`          | 回复 MR discussion   |
| `request_confirm_code`         | 申请危险操作确认码   |
| `delete_branch_confirmed`      | 删除分支（需确认码） |

## 可用 Prompts

| Prompt                  | 说明                      |
| ----------------------- | ------------------------- |
| `summarize_mr`          | 总结 MR 变更              |
| `review_mr_and_comment` | 评审 MR 并落行内评论      |
| `run_pipeline_master`   | 触发 master 分支 pipeline |

## License

MIT