GitLab MCP Server

将你的 AI 助手连接到 GitLab，让它可以用自然语言审查合并请求、处理流水线、管理议题并起草发布说明。 一个静态二进制文件（或容器），通过完整的 REST + GraphQL API 提供 1000+ 个 GitLab 工具，可与 Claude、Cursor、VS Code 以及任何 MCP 客户端配合使用。

你只需与 AI 助手对话，GitLab 的工作由它来完成。无需记住项目 ID、API 端点或 JSON。

"审查合并请求 !15 —— 可以安全合并吗？" · "上一次流水线为什么失败？" · "列出分配给我的公开议题" · "生成从 v1.0 到 v2.0 的发布说明"

🤖 正在使用 AI 助手？ 把这个仓库的 URL 交给它，让它为你的客户端安装服务器。模型要无头完成这件事所需的一切 —— 声明式的各客户端配置、claude mcp add 单行命令和默认值 —— 都在 llms.txt 中（无需交互式向导）。

60 秒内完成安装

任选一种方式。无论哪条路径，最后都是你向助手输入一条提示。

一键安装

每个按钮都会注册基于 Docker 的服务器（首次运行时会自动拉取镜像；你需要安装 Docker）。Claude Desktop 那一行则是下载原生 .mcpb 桌面扩展（macOS 通用版 + Windows，无需 Docker）—— 用 Claude Desktop 打开它并填写设置。需要令牌？创建一个具有 api 作用域的个人访问令牌。使用自托管 GitLab？安装后在客户端的 MCP 配置中添加 GITLAB_URL 环境变量。

Claude Code (claude mcp add)

Docker（无需安装 —— 首次运行时会拉取镜像）：

claude mcp add gitlab --env GITLAB_TOKEN=glpat-xxxx --transport stdio \
  -- docker run -i --rm -e GITLAB_TOKEN ghcr.io/jmrplens/gitlab-mcp-server:latest --http=false

或者先安装原生二进制文件，再注册它：

# macOS/Linux (Homebrew)
brew install jmrplens/tap/gitlab-mcp-server
# Linux/macOS (script)
curl -fsSL https://raw.githubusercontent.com/jmrplens/gitlab-mcp-server/main/scripts/install.sh | sh
# Windows (winget)
winget install --id jmrplens.gitlab-mcp-server -e
# Windows (PowerShell)
irm https://raw.githubusercontent.com/jmrplens/gitlab-mcp-server/main/scripts/install.ps1 | iex

claude mcp add gitlab --env GITLAB_TOKEN=glpat-xxxx -- gitlab-mcp-server

使用自托管 GitLab？添加 --env GITLAB_URL=https://gitlab.example.com（如果是自签名证书，再加上 --env GITLAB_SKIP_TLS_VERIFY=true）。

引导式设置（适用于任何客户端，无需记住参数）

该二进制文件自带一个 设置向导，它会收集你的 GitLab 令牌并为你配置 MCP 客户端 —— 如果你不想手改 JSON，这会很方便：

gitlab-mcp-server --setup

它会自动检测 VS Code、Claude Desktop、Claude Code、Cursor 和 Windsurf，并写入正确的配置。在 Windows 上，双击 .exe 即可启动它。

手动 JSON（Claude Desktop、Cursor、VS Code 等）

原生二进制文件（Claude Desktop 的 mcpServers、Cursor 等）：

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "env": { "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

VS Code（.vscode/mcp.json，注意 servers + type）：

{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "/path/to/gitlab-mcp-server",
      "env": { "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

Docker 变体 —— 将 "command"/"args" 替换为：

"command": "docker",
"args": ["run", "-i", "--rm", "-e", "GITLAB_TOKEN", "ghcr.io/jmrplens/gitlab-mcp-server:latest", "--http=false"]

Cline（VS Code）—— 打开 Cline 侧边栏 → MCP 服务器图标 → 编辑全局 MCP，或者直接编辑设置文件：

• macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

• Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

• Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

对于原生二进制文件，Cline 使用上面所示的 mcpServers 结构。

如需共享、长期运行的 HTTP 部署，而不是每用户的 stdio，请参阅 HTTP 服务器模式。

无需安装即可试用（托管端点）

一个公共实例运行在 https://mcp.jmrp.io/gitlab —— 无需安装任何组件，除了你自己的 GitLab 令牌外无需任何账号。让任何支持 HTTP 的 MCP 客户端指向它：

{
  "mcpServers": {
    "gitlab": {
      "type": "http",
      "url": "https://mcp.jmrp.io/gitlab",
      "headers": { "PRIVATE-TOKEN": "glpat-xxxxxxxxxxxx" }
    }
  }
}

PRIVATE-TOKEN 是必需的，并随每个请求传递 —— 它永远不会存储在服务器上。GITLAB-URL 是可选的，默认值为 https://gitlab.com；设置它可以访问另一个实例（该实例必须能从公共互联网访问）。

这是试用服务器最快的方式，但长期使用的正确方式仍然是 本地运行（上面任一选项）—— 之所以这样说，是出于一个具体原因，而不是作为免责声明：你的令牌和每个请求都会经过别人的机器。 在本地运行意味着你的凭据和 GitLab 流量永远不会离开你的电脑，这也使其成为私有自托管实例唯一明智的选择。

该端点是默认 dynamic 面上的 无状态流式 HTTP：POST 是传输方式，对其执行 GET 按设计返回 405，而 https://mcp.jmrp.io/gitlab/health 返回 200 及 {"status":"ok",…}。自托管的 HTTP 部署还可以运行 --auth-mode=oauth --gitlab-url=https://gitlab.com --public-url=https://mcp.example.com（两者都是必需的：OAuth 需要一个固定的实例，以及一个可从外部访问的源，RFC 9728 用它来标识资源）。在这种模式下，客户端通过该元数据发现 GitLab 为授权服务器，并在浏览器中完成授权，而不是复制令牌 —— 请参阅 OAuth 应用设置。它是 mcp.jmrp.io 上列出的服务器之一，该目录收录了我维护的 MCP 服务器，每个服务器都可以通过自己的端点访问；https://mcp.jmrp.io/servers.json 是面向自动化客户端的同一份列表。

然后直接提问： 打开你的 AI 客户端，试试 “列出我的 GitLab 项目。” 关于各客户端的详细信息，请参阅入门指南和更多示例提示。

Related MCP server: mcp-gitlab-jira

为什么选择这个服务器

• 自然语言操作 GitLab。 AI 会把“MR !15 可以安全合并吗？”转换成正确的 API 调用。你无需接触端点、ID 或 JSON。

• 覆盖整个平台 — 1000+ 工具。 广泛支持 GitLab REST v4 + GraphQL：项目、分支、标签、发布、合并请求、问题、流水线、作业、群组、用户、Wiki、环境、部署、包、容器镜像仓库、Runner、功能开关、CI/CD 变量、安全、管理、令牌等。

• 默认低 Token 消耗。 默认的 dynamic 表面只暴露 2 个工具（find + execute），但能触达完整目录 — 因此适合任何客户端的上下文窗口。（Token 占用 →）

• 经真实模型验证。 自动化评估器针对真实 GitLab 实例运行 Anthropic、Google、OpenAI 和 Qwen：在数千次操作中实现 99.5% 的总体成功率。（结果 →）

• 设计上安全。 只读模式、安全模式（每次变更的 dry-run 预览）、针对自托管 GitLab 的 TLS 选项，以及持续的 SonarCloud 质量/安全门禁。

• 随处运行。 单个静态二进制文件或容器；支持 Windows、Linux 和 macOS；amd64 和 arm64；stdio（桌面端）和 HTTP（远程）。

• 45 个 MCP 资源（只读数据：项目、问题、流水线、MR、分支、成员、感知工具表面的 gitlab://tools 清单，以及工作流最佳实践指南）。另有 26 种单对象类型支持订阅。

• 37 个 MCP 提示词（代码审查、流水线状态、风险评估、发布说明、站会、分析、审计等）。

• 4 个引导向导（交互式创建问题/MR/发布/项目）。

• 4 项 MCP 能力（补全、进度、引导，以及资源订阅 — 通过轮询支持的实时 resources/updated 通知）和 51 个工具图标（50 个领域图标加项目标志），用于在 MCP 客户端中进行可视化识别。

• 每个列表端点均支持分页，并附带完整元数据。

工具表面

服务器可以通过三种形态呈现 GitLab，由 TOOL_SURFACE 控制。默认形态无需任何配置。

工具数量会随你的 GitLab 版本（GITLAB_TIER）而变化；更高的版本层级会暴露更多操作。有关排序模型、安全防护和完整目录，请参阅 Dynamic Toolset 和 Meta-Tools Reference。在动态模式下，如果资源占用了大部分上下文，请设置 CAPABILITY_SURFACE=minimal。

Token 占用

基于当前目录，使用 go run ./cmd/audit_tokens/ -footprint 进行测量。总数估算 MCP 客户端启动时可见的上下文：可见的工具 schema 加上共享资源和提示词，使用 cl100k_base 分词器（GPT-4/GPT-3.5 编码）。完整矩阵（meta 和 individual 表面、所有 META_PARAM_SCHEMA 模式）请参阅 Token Footprint Reference。

默认配置：当 TOOL_SURFACE 未设置或为 TOOL_SURFACE=dynamic、CAPABILITY_SURFACE=full、META_TOOLS 未设置、META_PARAM_SCHEMA=opaque，且 GITLAB_TIER 未设置（自动检测，回退为 free）时，服务器使用 dynamic find/execute 表面。只有当你明确需要领域 meta-tools 时才使用 TOOL_SURFACE=meta；只有当你的客户端能够处理完整工具目录时才使用 TOOL_SURFACE=individual。

除非 Tier 列另有说明，各行均使用基础 Community Edition 目录。GITLAB_TIER 控制哪些操作可用；更高的版本层级会暴露更多工具，从而提供更多可触达的操作。

兼容性

已在以下环境中测试：VS Code + GitHub Copilot、Claude Desktop、Claude Code、Cursor、Windsurf、JetBrains IDE、Zed、Kiro、Cline。完整的 Compatibility Matrix 请参见此处。

AI 模型工具调用评估

该项目包含一个自动化评估器，用于评估面向模型的 MCP 质量。它可以对工具目录执行仅限 schema 的检查，也可以通过 MCP 对填充了 fixtures 的 Docker GitLab CE 或已授权 Enterprise 实例执行经过验证的模型工具调用。它衡量每个模型是否选择了正确的操作、发送了有效的参数、能从可操作的 GitLab 错误中恢复，以及是否遵守破坏性操作防护 — 覆盖 Anthropic、Google、OpenAI 和 Qwen。

当前发布结果：Docker CE dynamic 20260627-232303。

已发布的模型评估集涵盖 596 次任务尝试和 2220 个预期 MCP 操作。在所选报告中，模型在 2265 次模型请求中产生了 2265 次工具调用，总体最终成功率为 99.5%。详细的最新矩阵请参阅 AI Model Evaluation Results。

当前发布结果：Docker Enterprise meta 20260527。

已发布的模型评估集涵盖 92 次任务尝试和 336 个预期 MCP 操作。在所选报告中，模型在 350 次模型请求中产生了 345 次工具调用，总体最终成功率为 100.0%。详细的最新矩阵请参阅 AI Model Evaluation Results。

当前发布结果：Docker Enterprise dynamic 20260628-015421。

已发布的模型评估集涵盖 124 次任务尝试和 808 个预期 MCP 操作。在所选报告中，模型在 817 次模型请求中产生了 817 次工具调用，总体最终成功率为 100.0%。详细的最新矩阵请参阅 AI Model Evaluation Results。

文档

完整文档位于 jmrp.io/docs/gitlab-mcp-server。如需查找特定领域的权威参考，请使用此导航表：

常见问题

是的。将 GITLAB_URL 设置为您实例的 URL。省略 GITLAB_URL 时，stdio 模式使用 https://gitlab.com。通过 GITLAB_SKIP_TLS_VERIFY=true 支持自签名 TLS 证书。

当您自行运行时——在本地通过 stdio，或在您自己的基础设施上通过 HTTP——所有 API 调用都会直接发送到您的 GitLab 实例。唯一会发往其他地方的请求是针对 GitHub Releases 的更新检查，该检查默认开启，可通过 AUTO_UPDATE=false 关闭。

例外是托管端点：使用 https://mcp.jmrp.io/gitlab 意味着您的 token 和每个请求都会经过那台机器。那里不会存储任何内容，但那是别人的服务器，这正是托管部分建议您继续在本地使用它的原因。

关于更新检查具体发送的内容，请参阅 PRIVACY.md；关于安全模型，请参阅 SECURITY.md。

可以。设置 GITLAB_READ_ONLY=true 可禁用所有变更类工具（创建、更新、删除）。此时只有只读操作可用。

或者，设置 GITLAB_SAFE_MODE=true 进入试运行模式：变更类工具仍然可见，但会返回结构化的 JSON 预览，而不会实际执行。适用于审计、培训或审查 AI 助手会执行的操作。

社区版（CE）和企业版（EE）均受支持。在 stdio 模式下设置 GITLAB_TIER=premium 或 GITLAB_TIER=ultimate，可为 Premium/Ultimate 功能（DORA 指标、漏洞、合规性等）启用附加工具；不设置时，则根据实例许可证检测层级（回退为 free）。在 HTTP 模式下，--tier 可以强制指定层级，否则会根据许可证按每个 token+URL 池条目进行检测。

服务器包含针对 GitLab API 速率限制的带退避的重试逻辑。错误会被分类为临时性（可重试）或永久性，并在错误消息中提供可操作的提示。

任何兼容 MCP 的客户端：VS Code + GitHub Copilot、Claude Desktop、Cursor、Claude Code、Windsurf、JetBrains IDE、Zed、Kiro 等。内置的设置向导可以自动配置大多数客户端。

从源码构建

git clone https://github.com/jmrplens/gitlab-mcp-server.git
cd gitlab-mcp-server
make build

已发布的容器镜像是 ghcr.io/jmrplens/gitlab-mcp-server:latest。有关交叉编译、Docker Compose 和贡献指南，请参阅开发指南。

隐私政策

服务器完全在您的机器上运行，没有自己的遥测、分析或后端——数据仅在您的 MCP 客户端与您配置的 GitLab 实例之间流动（外加一次可选的、针对 GitHub Releases 的签名二进制更新检查）。您的 token 仅用于对 GitLab 请求进行身份验证，绝不会被记录。完整详情：PRIVACY.md。

贡献与安全

• 贡献：有关开发指南、分支命名、提交约定和 PR 流程，请参阅 CONTRIBUTING.md。

• 安全：有关安全策略和漏洞报告，请参阅 SECURITY.md。

• 行为准则：请参阅 CODE_OF_CONDUCT.md（贡献者公约 v2.1）。

仓库镜像：GitHub 是权威仓库。为了便于发现，GitLab.com 上提供只读镜像；请在 GitHub 上提交贡献。

文件数量

函数

值得注意的比率

代码模式

项目

纪录榜

为什么不呢