高级 GitLab MCP 服务器

高级 GitLab MCP 服务器——包含 18 种实体类型的 44 个工具，采用 CQRS 架构、OAuth 2.1 以及多种传输模式。

快速开始

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@structured-world/gitlab-mcp"],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "https://gitlab.com"
      }
    }
  }
}

要求： Node.js >= 24

Related MCP server: gitlab-mcp

亮点

• 44 个工具，涵盖 18 种实体类型——项目、合并请求、流水线、工作项、Wiki 等

• CQRS 架构——browse_* 用于查询，manage_* 用于命令

• 连接弹性——受限启动、带指数退避的自动重连、GitLab 不可达时的断开模式

• 多实例支持——通过每实例 OAuth 和速率限制连接到多个 GitLab 实例

• 多种传输方式——stdio, SSE, StreamableHTTP

• OAuth 2.1——通过 Claude 自定义连接器进行用户身份验证

• 只读模式——生产环境的安全操作

• 自动发现——从 git 远程仓库检测 GitLab 配置

• 细粒度控制——启用/禁用工具组、过滤操作、自定义描述

• Docker 支持——ghcr.io/structured-world/gitlab-mcp:latest

文档

完整文档请访问 gitlab-mcp.sw.foundation

自动生成的工具参考

获取包含参数的完整工具参考：

# View locally
yarn list-tools --detail

# Generate documentation
yarn list-tools --export --toc > docs/tools/api-reference.md

请参阅 完整 API 参考 获取自动生成的工具文档。

Docker

# HTTP mode
docker run -e PORT=3002 -e GITLAB_TOKEN=your_token -p 3333:3002 \
  ghcr.io/structured-world/gitlab-mcp:latest

# stdio mode
docker run -i --rm -e GITLAB_TOKEN=your_token \
  ghcr.io/structured-world/gitlab-mcp:latest

连接弹性

服务器可以优雅地处理 GitLab 连接问题：

• 受限启动——无论 GitLab 是否可用，服务器都会在 GITLAB_INIT_TIMEOUT_MS（默认 5 秒）内启动

• 断开模式——当 GitLab 不可达（disconnected/failed 状态）时，仅暴露 manage_context 工具，包含用于诊断的本地操作，如 whoami、switch_profile 和 set_scope。在主动重连（connecting 状态）期间，完整的工具列表仍然可用，因此 MCP 客户端在短暂中断期间不会丢失其工具目录。MCP 客户端会通过 tools/list_changed 收到工具可用性变更的通知

• 自动重连——指数退避重连（5 秒 → 60 秒），带有 ±10% 的抖动

• 错误分类——瞬时错误（网络、5xx、超时）会触发自动重连。启动时的身份验证/配置错误会转换为 failed 状态（不进行自动重连）。会话中令牌撤销通过与每次定期健康检查并行运行的已验证 HEAD /api/v4/user 检查来检测（仅限静态令牌模式；OAuth 模式下跳过）。此检查返回 401 或 403 会立即将实例转换为 failed 状态。

• 实例健康监控——每个受监控的实例 URL 都有自己的 XState 状态机。未跟踪的 OAuth URL 目前被视为可达。

功能标志

贡献

请参阅 CONTRIBUTING.md 获取开发设置、测试和 PR 指南。

支持项目

USDT (TRC-20): TFDsezHa1cBkoeZT5q2T49Wp66K8t2DmdA

许可证

Apache License 2.0 — 详情请参阅 LICENSE。

基于 zereight/gitlab-mcp (MIT)。请参阅 LICENSE.MIT。