GitLab MCP Server已精选

什么是 GitLab MCP Server？

GitLab MCP Server 是一个 gitlab mcp 集成，让 AI 助手可以通过 GitLab API 搜索项目、读取文件、推送提交，并创建 issue、分支、fork 和合并请求。本页收录的是已归档的参考版本；GitLab 现在已提供官方维护的 MCP 服务器。

本页收录的软件包 @modelcontextprotocol/server-gitlab 是 Model Context Protocol 项目发布的参考服务器之一。它已迁移到 servers-archived 仓库，该仓库说明其中的服务器不再维护、也不提供任何安全保证，npm 上的该软件包也已标记为不再支持。新部署请使用官方 GitLab MCP 服务器，它是内置于 GitLab 的远程端点，地址为 /api/v4/mcp。下文同时介绍这两种方式。

如何使用 GitLab MCP Server？

官方 GitLab MCP 服务器（推荐）

前提条件：在 GitLab.com 上需为你的顶级群组允许访问 MCP 服务器；在 GitLab Self-Managed 和 GitLab Dedicated 上需为实例允许访问。认证使用 OAuth：首次连接时，客户端会自行注册（OAuth 2.0 Dynamic Client Registration），打开浏览器，由你批准请求。服务器也接受带有 MCP 工具权限的细粒度个人访问令牌，但不接受旧版个人访问令牌、项目访问令牌或群组访问令牌。

在下面的示例中，将 <gitlab.example.com> 替换为 gitlab.com 或你的自托管实例 URL。

Claude Code

claude mcp add -s user --transport http GitLab https://<gitlab.example.com>/api/v4/mcp

启动 claude，输入 /mcp，选择 GitLab 服务器，然后在浏览器中批准授权。

Claude Desktop

需要 Node.js 20 或更高版本。将以下内容添加到 claude_desktop_config.json，然后重启 Claude Desktop：

{
  "mcpServers": {
    "GitLab": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<gitlab.example.com>/api/v4/mcp"]
    }
  }
}

Cursor

在 Settings > Cursor Settings > Tools & MCP 中，向 mcp.json 添加一个新的 MCP 服务器：

{
  "mcpServers": {
    "GitLab": {
      "type": "http",
      "url": "https://<gitlab.example.com>/api/v4/mcp"
    }
  }
}

VS Code

打开命令面板，运行 MCP: Add Server，选择 HTTP，输入 https://<gitlab.example.com>/api/v4/mcp，ID 填 GitLab，然后批准 OAuth 请求。

Codex

codex mcp add GitLab --url "https://<gitlab.example.com>/api/v4/mcp"
codex mcp login GitLab

GitLab 文档还要求在 ~/.codex/config.toml 的 [features] 中启用 rmcp_client。

已归档的参考服务器（本页显示的配置）

创建一个带 api 权限范围的 GitLab 个人访问令牌（只读访问可用 read_api），然后通过 npx 运行软件包：

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

GITLAB_API_URL 为可选项，仅自托管实例需要。README 还提供了 Docker 镜像 mcp/gitlab。

GitLab MCP Server 的主要功能

• 官方服务器内置于 GitLab，在 GitLab.com、Self-Managed 和 Dedicated 的 Free、Premium、Ultimate 版本中均可用；自 GitLab 19.5 起正式发布（GA）。
• HTTP 客户端无需本地安装：连接 https://<instance>/api/v4/mcp 并用 OAuth 登录即可。
• 提供 core、merge_requests、work_items、repository、ci 等工具组（toolsets），可通过 X-Gitlab-Enabled-Mcp-Server-Toolsets 请求头选择。
• 可通过 X-Gitlab-Mcp-Server-Tool-Name-Prefix 请求头为工具名添加前缀，便于同时连接多个 GitLab 实例。
• 每次工具调用都会检查你本人在项目和命名空间上的权限。
• 已归档服务器在创建或更新文件时会自动创建不存在的分支，并支持单文件和多文件提交，且不会强制推送。

GitLab MCP Server 工具

已归档的参考服务器提供本页列出的九个工具：

• 仓库与文件： search_repositories、create_repository、fork_repository、create_branch、get_file_contents。
• 提交： create_or_update_file 写入单个文件，push_files 在一次提交中推送多个文件。
• 协作： create_issue 和 create_merge_request（支持草稿）。

官方 GitLab MCP 服务器提供更丰富且持续维护的工具集，包括 get_merge_request_diffs、save_merge_request_review、list_pipelines、get_job、list_work_items、semantic_search，以及 Ultimate 版的漏洞相关工具。最新列表请参阅 GitLab 的 MCP 服务器工具文档。

GitLab MCP Server 的使用场景

• 代码评审：“总结合并请求 !42 的 diff，并列出有风险的改动。”
• Issue 分类：“在 my-group/api 中创建一个标题为 ‘Login timeout’ 的 issue，并加上 bug 标签。”
• 在对话中完成小修复：“创建分支 fix-readme，更新 README.md，并打开一个草稿合并请求。”
• CI 调试（官方服务器）：“main 上最新的流水线为什么失败？显示失败作业的日志。”
• 代码库问答：“读取 develop 分支上的 src/config.ts，并解释其中的默认值。”

GitLab MCP Server 与替代方案对比

• 官方 GitLab MCP 服务器与本归档软件包： 官方服务器由 GitLab 维护，使用 OAuth 而非长期有效的令牌，覆盖流水线、工作项和评审，HTTP 客户端无需运行本地进程。归档软件包只覆盖基础的仓库、issue 和合并请求操作。
• 社区 GitLab 服务器： 例如 GitLab MR MCP，专注于合并请求和 issue。
• 使用 GitHub 而非 GitLab： 请使用 GitHub MCP Server。

GitLab MCP Server 常见问题排查

• 官方服务器返回 403 Forbidden（GitLab 19.4 及更早版本为 404 Not Found）：你的群组或实例未允许 MCP 服务器，或你使用了旧版个人、项目或群组访问令牌。请检查前提条件，并改用 OAuth 或细粒度令牌。
• 429 Too Many Requests： 触发了 MCP 或 API 速率限制；在限制重置前请求都会失败。
• 使用 mcp-remote 时 OAuth 反复失败： 用 rm -rf ~/.mcp-auth/mcp-remote* 删除本地认证缓存后重新连接。
• 归档服务器返回认证错误： 确认 GITLAB_PERSONAL_ACCESS_TOKEN 具有 api 权限范围；自托管 GitLab 的 GITLAB_API_URL 需以 /api/v4 结尾。