mcp-gitlab

技能简介

mcp-gitlab 是一款基于 Model Context Protocol（MCP）的 GitLab REST API 服务器，为 AI 编程助手提供 83 个工具函数、7 个资源和 6 个提示词模板，全面覆盖 GitLab 项目管理、合并请求（MR）、管道（Pipeline）、CI/CD 变量、代码审批、Issue 和代码审查等开发工作流。它由开发者 vish288 基于 FastMCP 框架构建，支持 Claude Desktop、Claude Code、Cursor、Windsurf、VS Code Copilot 等所有 MCP 兼容客户端，同时兼容 GitLab.com 和自托管 GitLab 实例（CE/EE），无需付费的 GitLab Duo 或高级许可证即可使用。

核心能力

mcp-gitlab 提供 83 个工具函数，覆盖以下主要领域：

• 项目管理：获取项目详情、创建项目、删除项目、更新合并设置
• 合并请求（MR）：列出/获取/创建/更新/合并 MR，支持顺序合并、变基、变更审查、审批/取消审批、获取审批状态、列出管道和提交、订阅/取消订阅通知
• 管道（Pipeline）：列出/获取/创建管道，获取管道作业（带日志），重试或取消失败的管道
• 分支管理：列出/创建/删除分支
• 提交操作：列出/获取提交（含 diff）、创建提交（含文件操作）、比较分支/标签/提交
• 代码审批：项目级审批配置（CRUD）、MR 级审批规则（CRUD），完整覆盖团队代码审查流程
• CI/CD 变量：项目级和组级变量分别提供 CRUD 操作
• Issue 管理：列出/获取/创建/更新 Issue，添加评论
• 发布（Release）管理：列出/获取/创建/更新/删除发布
• MR 讨论与注释：创建行内讨论、多行讨论、回复、标记已解决；添加/删除/更新评论，评审 emoji

安装配置

安装方式（二选一）：

# 方式一：通过 uvx 运行（推荐，无需安装到系统）
uvx mcp-gitlab

# 方式二：通过 pip/uv 安装
uv pip install mcp-gitlab

环境变量配置（必填）：

Token 类型支持（按优先级自动识别）：

Token 权限要求：读取操作需 Reporter 角色；创建分支/MR/Issue 需 Developer；合并 MR/管理 CI/CD 变量需 Maintainer；删除项目需 Maintainer/Owner。

使用步骤

第一步：在 AI 助手中添加 MCP 服务器

以 Claude Code 为例：

claude mcp add gitlab -- uvx mcp-gitlab

以 Cursor 为例：访问 https://vish288.github.io/mcp-install?server=mcp-gitlab&install=cursor 使用一键安装链接。

第二步：配置环境变量

在 MCP 配置中传入环境变量：

{
  "mcpServers": {
    "gitlab": {
      "command": "uvx",
      "args": ["mcp-gitlab"],
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

第三步：验证连接

在 AI 助手中尝试基本查询：

列出项目 my-org/api-gateway 的基本信息

第四步：日常工作流

• 发起 MR 并自动化审查：让 AI 助手获取 MR 变更 → 检查管道状态 → 撰写行内评论 → 审批
• 管道故障诊断：让 AI 助手获取失败的管道作业日志 → 分析原因 → 给出修复建议
• Issue 批量处理：让 AI 助手列出某个标签下的所有 Issue → 分类 → 优先级排序

适用场景

• 团队批量 GitLab 操作：一次对话中批量创建分支、发起 MR、更新 CI/CD 变量，无需频繁切换 UI
• AI 辅助代码审查：AI 助手自动获取 MR 变更、审查代码质量、撰写行内讨论、评估合并就绪状态
• DevOps 管道自动化：监控管道状态、重试失败作业、获取构建日志、诊断 CI 故障
• 开发工作流集成：与 Git 工作流（分支规范、合并规范、提交规范）结合，规范团队协作
• Issue 与项目管理：AI 辅助创建、分类、标注 Issue，跟踪项目进度

适用人群

• DevOps 工程师：日常管理 GitLab 管道和 CI/CD 变量，自动化重复性运维操作
• 开发团队：通过 AI 助手高效处理 MR、代码审查、Issue 等协作事务
• AI 开发者：构建基于 GitLab 的 AI 编程工作流，将 GitLab 操作融入 AI Agent
• GitLab 管理员：批量管理组/项目权限、审批规则和发布流程

工作原理

mcp-gitlab 运行在 AI 助手（如 Claude Code）和 GitLab REST API 之间，本质是一个 MCP 协议代理层。它基于 FastMCP 框架实现，该框架基于 Model Context Protocol 规范构建，将 GitLab REST API 的各种端点封装为标准化的 MCP 工具函数（Tool），暴露给 AI 助手调用。服务器通过 httpx 库向 GitLab API 发起 HTTP 请求，使用 Pydantic 对请求参数和响应数据进行严格的数据模型验证。服务器支持 stdio 和 HTTP（SSE/streamable-http）两种传输协议，兼容各类 MCP 客户端生态。此外，服务器内置只读模式（GITLAB_READ_ONLY=true），可在共享给 AI 助手时禁用一切写操作，防止意外修改生产环境配置。所有凭证仅从环境变量读取，服务器本身不存储任何认证信息。

官方链接

• PyPI：https://pypi.org/project/mcp-gitlab
• GitHub：https://github.com/vish288/mcp-gitlab
• MCP Registry：https://registry.modelcontextprotocol.io
• 安装网关：https://vish288.github.io/mcp-install?server=mcp-gitlab