Advanced GitLab MCP server

高级 GitLab MCP 服务

高级 GitLab MCP 服务——提供 64 个 CQRS 工具，涵盖 26 种实体类型的 234 项 GitLab 操作。工具目录和参数会根据各实例的 GitLab 版本、层级和令牌权限进行筛选，因此 Agent 只能看到所连接实例实际支持的功能。

软件包

这是一个包含两个 npm 软件包的 monorepo：

• @structured-world/gitlab-mcp — MCP 服务。支持内存和文件 OAuth 会话存储，无需依赖数据库。这是大多数用户所需的全部内容。
• @structured-world/gitlab-mcp-db — 可选的 PostgreSQL/Prisma OAuth 会话后端，适用于在负载均衡器后运行多个副本。通过 OAUTH_STORAGE_TYPE=postgresql 启用；完整设置方法请参阅 PostgreSQL 部署指南。

快速开始

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

亮点

• 64 个工具，涵盖 26 种实体类型——项目、合并请求、流水线、工作项、Wiki 等
• CQRS 架构——使用 browse_* 执行查询，使用 manage_* 执行命令
• 连接弹性——有界启动、指数退避自动重连，以及 GitLab 无法访问时的断连模式
• 多实例支持——通过各实例独立的 OAuth 和速率限制连接 GitLab.com、自托管和自行管理的实例；一个连接可以关联多个账户，例如公司的 GitLab 和个人的 GitLab.com 账户，每个聊天会话都可以在这些账户之间切换
• 多种传输方式——stdio、SSE、StreamableHTTP
• OAuth 2.1——通过 Claude Custom Connector 进行用户级身份验证
• 只读模式——适用于生产环境的安全操作
• 自动发现——从 git 远程仓库检测 GitLab 配置
• 精细化控制——启用/禁用工具组、筛选操作、自定义描述
• Docker 支持——ghcr.io/structured-world/gitlab-mcp:latest

工具模型

GitLab 提供数百种 API 操作。为每种操作都提供一个 MCP 工具会塞满 Agent 的上下文；轻量级 API 封装则会把这种复杂性推回给 Agent。此服务采用第三条路径：64 个 CQRS 工具，每个工具包含多个类型化操作，覆盖 26 种实体类型的 234 种操作。

• browse_* 工具用于只读查询；manage_* 工具用于写入。
• 子资源整合为操作，而不是新增工具——browse_pipelines 在单个工具中涵盖流水线、作业和日志。
• 工具列表、操作和参数会在生成架构时，根据 GitLab 版本、层级、令牌范围、管理员模式、功能标志和配置文件进行解析。

示例：

• browse_pipelines — 列表、获取、作业、作业详情、日志、触发器
• manage_pipeline — 创建、重试、取消
• browse_environments — 列表、获取、列出部署
• manage_environment — 创建、更新、停止、删除、更新部署状态
• browse_deploy_keys / manage_deploy_key — 列表、获取 / 添加、启用、更新、删除

文档

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

章节	说明
安装	npm、Docker、VS Code、Codex
配置	环境变量、功能标志
多实例	连接多个 GitLab 实例
工具参考	全部 64 个工具及其参数
OAuth 设置	使用 Claude 进行团队身份验证
TLS/HTTPS	使用 SSL 进行生产部署
自定义	工具描述、操作筛选
CLI 工具	浏览并导出工具文档

自动生成的工具参考

查看包含参数的完整工具参考：

# 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（默认 5s）内启动
• 断开连接模式 — GitLab 无法访问时（处于 disconnected/failed 状态），仅开放 manage_context 工具，并提供 whoami、switch_preset 和 set_scope 等本地操作用于诊断。在正在重新连接时（处于 connecting 状态），仍会提供完整的工具列表，避免 MCP 客户端在短暂中断期间丢失工具目录。工具可用性发生变化时，会通过 tools/list_changed 通知 MCP 客户端
• 自动重连 — 使用指数退避策略重连（5s → 60s），并加入 ±10% 的随机抖动
• 错误分类 — 临时错误（网络错误、5xx、超时）会触发自动重连。启动时发生的身份验证/配置错误会使状态变为 failed（不会自动重连）。在会话中途，系统会通过与每次定期健康检查同步运行的、经过身份验证的 HEAD /api/v4/user 检查，检测令牌是否被撤销（仅限静态令牌模式；OAuth 模式下跳过）。此检查返回 401 或 403 时，实例会立即变为 failed 状态。
• 实例健康监控器 — 每个受监控的实例 URL 都有自己的 XState 状态机。未跟踪的 OAuth URL 目前会直接视为可访问。

变量	默认值	说明
GITLAB_INIT_TIMEOUT_MS	5000	启动时等待 GitLab 的最长时间
GITLAB_RECONNECT_BASE_DELAY_MS	5000	初始重连延迟（每次尝试都会加倍）
GITLAB_RECONNECT_MAX_DELAY_MS	60000	最大重连延迟
GITLAB_HEALTH_CHECK_INTERVAL_MS	60000	已连接时的健康检查间隔
GITLAB_FAILURE_THRESHOLD	3	断开连接前连续发生临时故障的次数
GITLAB_TOOL_TIMEOUT_MS	120000	工具/引导执行超时前的最长时间
GITLAB_RESPONSE_WRITE_TIMEOUT_MS	10000	销毁僵尸连接前刷新非 SSE 响应的最长时间（设为 0 可禁用；SSE 使用心跳）
GITLAB_INSTANCE_CACHE_MAX	100	内存中保留的每 URL 实例状态的最大数量（OAuth 多租户；超出时按 LRU 策略淘汰）
GITLAB_INSTANCE_TTL_MS	3600000	每 URL 空闲实例状态的 TTL，单位为 ms；在下次插入时淘汰（OAuth 多租户）

功能标志

标志	默认值	启用的工具
USE_LABELS	true	标签管理
USE_MRS	true	合并请求
USE_FILES	true	文件操作
USE_VARIABLES	true	CI/CD 变量
USE_WORKITEMS	true	问题、史诗、任务
USE_WEBHOOKS	true	Webhook 管理
USE_SNIPPETS	true	代码片段
USE_INTEGRATIONS	true	50+ 项集成
USE_GITLAB_WIKI	true	Wiki 页面
USE_MILESTONE	true	里程碑
USE_PIPELINE	true	流水线与 CI/CD
USE_RELEASES	true	发布管理
USE_REFS	true	分支与标签管理
USE_MEMBERS	true	团队成员
USE_SEARCH	true	跨项目搜索
USE_ITERATIONS	true	迭代规划（冲刺）
USE_CI_TOKENS	true	CI 访问凭据：作业令牌范围和部署密钥
USE_ENVIRONMENTS	true	环境与部署
USE_RUNNERS	true	CI 运行器管理
USE_REGISTRY	true	容器注册表仓库和标签
USE_ACCESS_TOKENS	true	项目/群组/个人访问令牌管理
USE_AUDIT_EVENTS	true	审计事件（Premium+）
USE_VULNERABILITIES	true	漏洞管理（Ultimate）

参与贡献

开发环境设置、测试和 PR 指南，请参阅 CONTRIBUTING.md。

支持项目

## License

Apache License 2.0 — see LICENSE for details.

Based on zereight/gitlab-mcp (MIT). See LICENSE.MIT.