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/默认分支）

安装

# 全局安装（推荐）
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

{
  "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：

{
  "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 添加：

# 添加 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 目录：

# 项目级别
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，配置方式相同：

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 进行调试：

# 克隆项目
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