GitLab MCP 服务器

新功能：支持动态 GitLab API URL 并提供连接池！详情请参阅 动态 API URL 文档。

@zereight/mcp-gitlab

GitLab MCP（模型上下文协议）服务器。包含对原始 GitLab MCP 服务器的错误修复和改进。

使用方法

与 Claude Code、Codex、Antigravity、OpenCode、Copilot、Cline、Roo Code、Cursor、Kilo Code、Amp Code 配合使用

当与 Claude 应用程序一起使用时，您需要直接设置您的 API 密钥和 URLs。

认证方式

该服务器支持四种认证方式：

适用于本地/桌面使用（最常见）：

1. 个人访问令牌 (GITLAB_PERSONAL_ACCESS_TOKEN) — 最简单的设置
2. OAuth2 — 本地浏览器 (GITLAB_USE_OAUTH) — 推荐用于更高的安全性

适用于服务器/远程部署：

3. OAuth2 — MCP 代理 (GITLAB_MCP_OAUTH) — 用于远程 MCP 客户端，例如 Claude.ai
4. 远程授权 (REMOTE_AUTHORIZATION) — 多用户部署，每个调用者提供自己的令牌

使用 OAuth2 认证

OAuth2 提供了一种更安全的基于浏览器的身份验证流程。启用后，服务器将：

1. 打开您的浏览器到 GitLab 的授权页面
2. 等待您批准访问权限
3. 安全地存储令牌以供将来使用
4. 在令牌过期时自动刷新令牌

有关详细的 OAuth2 设置说明，请参阅 OAuth 设置指南。

快速设置 - 首先创建一个 GitLab OAuth 应用程序：

1. 前往您的 GitLab 实例：管理区域 → 应用程序
2. 创建一个新应用程序，设置如下：
   • 名称：GitLab MCP 服务器（或您喜欢的任何名称）
   • 重定向 URI：http://127.0.0.1:8888/callback
   • 作用域：选择 api（提供对 API 的完整读写访问权限）
3. 复制 应用程序 ID（即您的客户端 ID）

然后使用 OAuth 配置 MCP 服务器：

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_USE_OAUTH": "true",
        "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
        "GITLAB_OAUTH_CLIENT_SECRET": "your_oauth_client_secret", // 仅限机密应用
        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8888/callback",
        "GITLAB_API_URL": "your_gitlab_api_url",
        "GITLAB_PROJECT_ID": "your_project_id", // 可选：默认项目
        "GITLAB_ALLOWED_PROJECT_IDS": "", // 可选：允许的项目 ID 列表，用逗号分隔
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "false", // 是否使用 wiki API？
        "USE_MILESTONE": "false", // 是否使用里程碑 API？
        "USE_PIPELINE": "false" // 是否使用流水线 API？
      }
    }
  }
}

使用个人访问令牌（传统方式）

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "your_gitlab_api_url",
        "GITLAB_PROJECT_ID": "your_project_id", // 可选：默认项目
        "GITLAB_ALLOWED_PROJECT_IDS": "", // 可选：允许的项目 ID 列表，用逗号分隔
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "false", // 是否使用 wiki API？
        "USE_MILESTONE": "false", // 是否使用里程碑 API？
        "USE_PIPELINE": "false" // 是否使用流水线 API？
      }
    }
  }
}

使用 CLI 参数（适用于环境变量有问题的客户端）

一些 MCP 客户端（如 GitHub Copilot CLI）在处理环境变量时存在问题。您可以改用 CLI 参数：

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab",
        "--token=YOUR_GITLAB_TOKEN",
        "--api-url=https://gitlab.com/api/v4"
      ],
      "tools": ["*"]
    }
  }
}

可用的 CLI 参数：

• --token - GitLab 个人访问令牌（替代 GITLAB_PERSONAL_ACCESS_TOKEN）
• --api-url - GitLab API URL（替代 GITLAB_API_URL）
• --read-only=true - 启用只读模式（替代 GITLAB_READ_ONLY_MODE）
• --use-wiki=true - 启用 wiki API（替代 USE_GITLAB_WIKI）
• --use-milestone=true - 启用里程碑 API（替代 USE_MILESTONE）
• --use-pipeline=true - 启用流水线 API（替代 USE_PIPELINE）

CLI 参数优先于环境变量。

vscode .vscode/mcp.json

使用 OAuth2（非机密 - 推荐）：

{
  "servers": {
    "GitLab-MCP": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_USE_OAUTH": "true",
        "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8888/callback",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "false",
        "USE_MILESTONE": "false",
        "USE_PIPELINE": "false"
      }
    }
  }
}

使用 OAuth2（机密）：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitlab-oauth-secret",
      "description": "GitLab OAuth 客户端秘密",
      "password": true
    }
  ],
  "servers": {
    "GitLab-MCP": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_USE_OAUTH": "true",
        "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
        "GITLAB_OAUTH_CLIENT_SECRET": "${input:gitlab-oauth-secret}",
        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8888/callback",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "false"
      }
    }
  }
}

使用个人访问令牌：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitlab-token",
      "description": "GitLab 个人访问令牌",
      "password": true
    }
  ],
  "servers": {
    "GitLab-MCP": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${input:gitlab-token}",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "false",
        "USE_MILESTONE": "false",
        "USE_PIPELINE": "false"
      }
    }
  }
}

Strands Agents SDK（MCP 工具）

env_vars = {
        "GITLAB_PERSONAL_ACCESS_TOKEN": gitlab_access_token,
        "GITLAB_API_URL": gitlab_api_url,
        "USE_GITLAB_WIKI": use_gitlab_wiki
        # ......其余可选参数
}

stdio_gitlab_mcp_client = MCPClient(
        lambda: stdio_client(
            StdioServerParameters(
                command="npx",
                args=["-y", "@zereight/mcp-gitlab"],
                env=env_vars,
            )
        )
    )

Docker

注意: 对于 Docker 部署，推荐使用个人访问令牌。OAuth 需要基于浏览器的身份验证以及本地回调服务器，这在容器化环境中无法正常工作。

使用个人访问令牌（stdio） - 推荐：

{
  "mcpServers": {
    "gitlab": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITLAB_PERSONAL_ACCESS_TOKEN",
        "-e",
        "GITLAB_API_URL",
        "-e",
        "GITLAB_READ_ONLY_MODE",
        "-e",
        "USE_GITLAB_WIKI",
        "-e",
        "USE_MILESTONE",
        "-e",
        "USE_PIPELINE",
        "zereight050/gitlab-mcp"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "true",
        "USE_MILESTONE": "true",
        "USE_PIPELINE": "true"
      }
    }
  }
}

• sse

docker run -i --rm \
  -e HOST=0.0.0.0 \
  -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_READ_ONLY_MODE=true \
  -e USE_GITLAB_WIKI=true \
  -e USE_MILESTONE=true \
  -e USE_PIPELINE=true \
  -e SSE=true \
  -p 3333:3002 \
  zereight050/gitlab-mcp

{
  "mcpServers": {
    "gitlab": {
      "type": "sse",
      "url": "http://localhost:3333/sse"
    }
  }
}

• streamable-http

docker run -i --rm \
  -e HOST=0.0.0.0 \
  -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_READ_ONLY_MODE=true \
  -e USE_GITLAB_WIKI=true \
  -e USE_MILESTONE=true \
  -e USE_PIPELINE=true \
  -e STREAMABLE_HTTP=true \
  -p 3333:3002 \
  zereight050/gitlab-mcp

{
  "mcpServers": {
    "gitlab": {
      "type": "streamable-http",
      "url": "http://localhost:3333/mcp"
    }
  }
}

使用 MCP OAuth 代理 (GITLAB_MCP_OAUTH)

仅适用于服务器/远程部署。此模式要求 MCP 服务器部署在一个可公开访问的 HTTPS URL 上。对于本地/桌面使用，请参阅上面的 GITLAB_USE_OAUTH。

适用于支持 MCP OAuth 规范的远程 MCP 客户端（例如 Claude.ai）。 该服务器充当完整的 OAuth 2.0 授权服务器——未经身份验证的请求会收到 401 + WWW-Authenticate 响应，从而在客户端自动触发 OAuth 浏览器流程。

工作原理: 您将此 MCP 服务器部署在具有公共 HTTPS URL 的位置。MCP 客户端连接到 {MCP_SERVER_URL}/mcp。服务器会处理 OAuth 2.0 流程，并代表客户端与 GitLab 进行凭据交换。

先决条件:

1. 一个可公开访问的 HTTPS 服务器 URL (MCP_SERVER_URL) — 可使用 ngrok 进行本地测试
2. 已预先注册的 GitLab OAuth 应用程序，具有 api（或 read_api）范围 — 转到 Admin area → Applications，将重定向 URI 设置为 {MCP_SERVER_URL}/callback

环境变量	必需	描述
GITLAB_MCP_OAUTH	✅	设置为 true 以启用
GITLAB_API_URL	✅	GitLab API 基础 URL
GITLAB_OAUTH_APP_ID	✅	GitLab OAuth 应用程序 ID
MCP_SERVER_URL	✅	此 MCP 服务器的公共 HTTPS URL
STREAMABLE_HTTP	✅	必须为 true
GITLAB_OAUTH_SCOPES	可选	逗号分隔的范围（默认：api,read_api,read_user）

docker run -i --rm \
  -e HOST=0.0.0.0 \
  -e GITLAB_MCP_OAUTH=true \
  -e STREAMABLE_HTTP=true \
  -e MCP_SERVER_URL=https://your-server.example.com \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_OAUTH_APP_ID=your_app_id \
  -p 3000:3002 \
  zereight050/gitlab-mcp

MCP 客户端配置：

{
  "mcpServers": {
    "gitlab": {
      "type": "http",
      "url": "https://your-server.example.com/mcp"
    }
  }
}

使用远程授权 (REMOTE_AUTHORIZATION)

仅适用于服务器/远程部署。每个 HTTP 调用者直接在请求头中提供自己的 GitLab 令牌——不涉及 OAuth 流程。

适用于多用户或多租户部署，其中每个调用者都在 HTTP 请求头中提供自己的 GitLab 令牌。无需 OAuth 流程——MCP 服务器会代表调用者将令牌转发给 GitLab。

头优先级: Private-Token > JOB-TOKEN > Authorization: Bearer

环境变量	必需	描述
REMOTE_AUTHORIZATION	✅	设置为 true 以启用
STREAMABLE_HTTP	✅	必须为 true
ENABLE_DYNAMIC_API_URL	可选	允许通过 X-GitLab-API-URL 头部指定每请求的 GitLab URL

示例请求头:

Private-Token: glpat-xxxxxxxxxxxxxxxxxxxx

或者使用 Bearer 令牌：

Authorization: Bearer glpat-xxxxxxxxxxxxxxxxxxxx

⚠️ REMOTE_AUTHORIZATION 不兼容 SSE 传输。必须设置 STREAMABLE_HTTP=true。

环境变量

认证配置

• GITLAB_PERSONAL_ACCESS_TOKEN: 您的 GitLab 个人访问令牌。在标准模式下必填；当 REMOTE_AUTHORIZATION=true 或使用 OAuth 时，则不需此参数。
• GITLAB_USE_OAUTH: 设置为 true 以启用 OAuth2 身份验证，而非个人访问令牌。
• GITLAB_OAUTH_CLIENT_ID: 来自您的 GitLab OAuth 应用程序的客户端 ID。使用 OAuth 时必填。
• GITLAB_OAUTH_CLIENT_SECRET: 来自您的 GitLab OAuth 应用程序的客户端密钥。仅对机密应用必需。
• GITLAB_OAUTH_REDIRECT_URI: OAuth 回调 URL。默认值：http://127.0.0.1:8888/callback
• GITLAB_OAUTH_TOKEN_PATH: 自定义存储 OAuth 令牌的路径。默认值：~/.gitlab-mcp-token.json
• REMOTE_AUTHORIZATION: 当设置为 true 时，通过 HTTP 头部启用远程会话级授权。在此模式下：
  • 服务器会按会话接受来自 HTTP 头部的 GitLab PAT 令牌（Authorization: Bearer <token>、Private-Token: <token> 或 Job-Token: <token>）
  • GITLAB_PERSONAL_ACCESS_TOKEN 环境变量 无需设置，且会被忽略
  • 仅适用于 可流式传输的 HTTP 传输（STREAMABLE_HTTP=true），因为会话管理已由传输层处理
  • 禁用 SSE 传输 — 如果尝试在启用远程授权的情况下使用 SSE，服务器将报错并退出
  • 每个客户端会话可以使用不同的令牌，从而实现多用户支持，并确保会话的安全隔离
  • 令牌按会话存储，并在会话结束或超时时自动清除
• GITLAB_MCP_OAUTH: 设置为 true 以启用服务器端 MCP OAuth 代理模式。详情请参见 MCP OAuth 设置。
• GITLAB_OAUTH_APP_ID: 预注册 GitLab OAuth 应用程序的客户端 ID。当 GITLAB_MCP_OAUTH=true 时必填。
• GITLAB_OAUTH_SCOPES: 在 MCP OAuth 流程中请求的 GitLab 作用域列表，以逗号分隔（例如 api,read_user）。默认值为 api（或当 GITLAB_READ_ONLY_MODE=true 时为 read_api）。仅在 GITLAB_MCP_OAUTH=true 时使用。预注册的应用程序必须至少配置这些作用域。
• SESSION_TIMEOUT_SECONDS: 会话认证令牌的超时时间，单位为秒。默认值：3600（1 小时）。有效范围：1–86400 秒（建议 60 秒以上）。在此期间无活动后，认证令牌将被移除，但传输会话仍保持活动状态。客户端在下次请求时需重新提供认证头信息。仅适用于 REMOTE_AUTHORIZATION=true。

通用配置

• GITLAB_API_URL: 您的 GitLab API URL。（默认值：https://gitlab.com/api/v4）

• GITLAB_PROJECT_ID: 默认项目 ID。如果设置，则在进行 API 请求时覆盖该值。

• GITLAB_ALLOWED_PROJECT_IDS: 可选的允许项目 ID 列表，以逗号分隔。当仅设置一个值时，该值将作为默认项目（类似于旧版“锁定”模式）。当设置多个值时，则仅允许访问这些项目。示例：

  • 单一值 123：MCP 服务器只能访问项目 123，并将其用作默认项目。
  • 多个值 123,456,789：MCP 服务器可以访问项目 123、456 和 789，但每次请求都必须明确指定项目 ID。

• GITLAB_READ_ONLY_MODE: 当设置为 true 时，服务器仅暴露只读操作。这有助于增强安全性，或在不需要写入权限时使用。也适用于与 Cursor 及其 40 个工具限制一起使用。

• GITLAB_DENIED_TOOLS_REGEX: 当设置为正则表达式时，将排除匹配的工具。

• USE_GITLAB_WIKI: 遗留标志。Wiki 功能现已默认启用。当设置为 true 时，即使 wiki 工具集未在 GITLAB_TOOLSETS 中显式列出，也会确保包含 Wiki 相关工具。

• USE_MILESTONE: 遗留标志。里程碑功能现已默认启用。当设置为 true 时，即使 milestones 工具集未在 GITLAB_TOOLSETS 中显式列出，也会确保包含里程碑相关工具。

• USE_PIPELINE: 遗留标志。流水线功能现已默认启用。当设置为 true 时，即使 pipelines 工具集未在 GITLAB_TOOLSETS 中显式列出，也会确保包含流水线相关工具。

• GITLAB_TOOLSETS: 以逗号分隔的要启用的工具集 ID 列表。如果为空或未设置，则使用默认工具集。设置为 "all" 可启用所有工具集。可用工具集如下（默认工具集以 * 标记）：

  • merge_requests* — MR 操作、评论、讨论、草稿评论、线程、版本、文件差异、冲突（34 个工具）
  • issues* — 问题的 CRUD 操作、评论、链接、讨论（14 个工具）
  • repositories* — 搜索、创建、文件内容、推送、分支、树结构（7 个工具）
  • branches* — 分支创建、提交、差异比较（4 个工具）
  • projects* — 项目/命名空间信息、组内项目、迭代（8 个工具）
  • labels* — 标签的 CRUD 操作（5 个工具）
  • pipelines* — 流水线、作业、部署、环境及制品相关操作（19 个工具）
  • milestones* — 里程碑的 CRUD 操作、关联的问题和 MR、燃尽图（9 个工具）
  • wiki* — 项目和组级别的 Wiki 页面 CRUD 操作（10 个工具）
  • releases* — 发布物的 CRUD 操作、证据、资产下载（7 个工具）
  • users* — 用户信息、事件、Markdown 上传、附件（5 个工具）
  • workitems — 通过 GraphQL 进行工作项的 CRUD 操作、类型转换、状态、自定义字段、评论、时间线事件（12 个工具，需单独启用）
  • webhooks — Webhook 列表及事件检查（3 个工具，需单独启用）
  • search — 跨项目、跨组或全局代码搜索（3 个工具，需启用高级搜索或精确代码搜索）

  注意：execute_graphql 不属于任何工具集，如需使用，必须通过 GITLAB_TOOLS 单独添加。公开任意 GraphQL 查询可能会绕过工具集限制（例如查询用户通过工具集有意禁用的数据，如 Wiki 或流水线），这将带来安全和权限隔离方面的风险。因此，将 execute_graphql 排除在所有工具集之外，并要求通过 GITLAB_TOOLS=execute_graphql 显式启用，正是为了遵循这一原则，而非出于向后兼容性的考虑。命令行参数：--toolsets

• GITLAB_TOOLS: 以逗号分隔的单个工具名称列表，用于在已启用工具集的基础上进一步添加（累加方式）。可用于仅选择特定工具，而不必启用整个工具集。示例：GITLAB_TOOLS="list_pipelines,execute_graphql"。命令行参数：--tools

  综合逻辑：最终工具 = （已启用工具集中的工具） ∪ （GITLAB_TOOLS） ∪ （遗留标志的覆盖）

  示例：

  # 默认行为（不变）
  GITLAB_PERSONAL_ACCESS_TOKEN=xxx npx @zereight/mcp-gitlab
  
  # 仅限问题和仓库
  GITLAB_TOOLSETS="issues,repositories" npx @zereight/mcp-gitlab
  
  # 启用所有工具集
  GITLAB_TOOLSETS="all" npx @zereight/mcp-gitlab
  
  # 默认工具集 + 额外一个流水线工具
  GITLAB_TOOLS="list_pipelines" npx @zereight/mcp-gitlab
  
  # 特定工具集 + 单个工具
  GITLAB_TOOLSETS="issues,merge_requests" GITLAB_TOOLS="list_pipelines,get_pipeline" npx @zereight/mcp-gitlab
  

旧版标志仍有效（向后兼容）

USE_PIPELINE=true npx @zereight/mcp-gitlab

- `GITLAB_AUTH_COOKIE_PATH`: 用于需要基于 Cookie 认证的 GitLab 实例的认证 Cookie 文件路径。提供此参数后，该 Cookie 将被包含在所有 GitLab API 请求中。
- `SSE`: 设置为 'true' 时，启用服务器发送事件传输。
- `STREAMABLE_HTTP`: 设置为 'true' 时，启用可流式 HTTP 传输。如果 **SSE** 和 **STREAMABLE_HTTP** 均设置为 'true'，服务器将优先使用可流式 HTTP 而不是 SSE 传输。
- `GITLAB_COMMIT_FILES_PER_PAGE`: GitLab 返回的提交差异每页文件数量。此值应与服务器端 GitLab 设置一致。如果您的 GitLab 实例对提交差异使用自定义的每页值，请调整此参数。
- `GITLAB_REPO_FILE_ENCODING`: 发送到 GitLab API 的仓库文件创建/更新及相关提交负载的编码方式。可使用 `text`（默认）或 `base64`。等效 CLI 参数：`--repo-file-encoding=text|base64`。

#### 性能与安全配置

- `HOST`: 服务器主机地址。默认值：`127.0.0.1`（仅限本地访问）。设置为 `0.0.0.0` 可允许外部连接（Docker 使用端口转发时必需）。
- `MAX_SESSIONS`: 允许的最大并发会话数。默认值：`1000`。有效范围：1–10000。达到限制时，新连接将被拒绝，并返回 HTTP 503 错误。
- `MAX_REQUESTS_PER_MINUTE`: 每个会话每分钟的请求速率限制。默认值：`60`。有效范围：1–1000。超出限制的请求将返回 HTTP 429 错误。
- `PORT`: 服务器端口。默认值：`3002`。有效范围：1–65535。
- `HTTP_PROXY`: 用于出站请求的 HTTP 代理服务器 URL。示例：`http://proxy.example.com:8080`。支持 HTTP/HTTPS 和 SOCKS 代理（以 `socks://` 或 `socks5://` 开头的 URL）。CLI 参数：`--http-proxy`。
- `HTTPS_PROXY`: 用于出站请求的 HTTPS 代理服务器 URL。示例：`https://proxy.example.com:8080`。支持 HTTP/HTTPS 和 SOCKS 代理。CLI 参数：`--https-proxy`。
- `NO_PROXY`: 逗号分隔的应绕过代理的主机列表。支持：
- 完整主机名匹配（如 `localhost`、`gitlab.internal.com`）
- 域名后缀匹配（如 `.internal.com` 匹配任何子域名）
- IP 地址匹配（如 `127.0.0.1`、`192.168.1.1`）
- 端口特定匹配（如 `example.com:443`）
- 通配符 `*` 表示绕过所有主机的代理
- 示例：`NO_PROXY=localhost,127.0.0.1,.internal.com`
- CLI 参数：`--no-proxy`。

#### 监控端点

使用可流式 HTTP 传输时，以下端点可用：

- `/health`: 健康检查端点，返回服务器状态、活动会话数和运行时间。
- `/metrics`: 详细指标包括：
- 活动和总会话数
- 认证指标（失败、过期）
- 速率限制统计
- 资源使用情况（内存、运行时间）
- 配置摘要



### 远程授权设置（多用户支持）

当使用 `REMOTE_AUTHORIZATION=true` 时，MCP 服务器可以支持多个用户，每个用户通过 HTTP 头传递各自的 GitLab 令牌。这适用于以下场景：

- 共享的 MCP 服务器实例，其中每个用户需要自己的 GitLab 访问权限
- IDE 集成，可以将用户特定的令牌注入到 MCP 请求中

**设置示例：**

```bash
# 启动带有远程授权的服务器
docker run -d \
-e HOST=0.0.0.0 \
-e STREAMABLE_HTTP=true \
-e REMOTE_AUTHORIZATION=true \
-e GITLAB_API_URL="https://gitlab.com/api/v4" \
-e GITLAB_READ_ONLY_MODE=true \
-e SESSION_TIMEOUT_SECONDS=3600 \
-p 3333:3002 \
zereight050/gitlab-mcp

客户端配置：

您的 IDE 或 MCP 客户端必须在每次请求中发送以下其中一个头信息：

Authorization: Bearer glpat-xxxxxxxxxxxxxxxxxxxx

或

Private-Token: glpat-xxxxxxxxxxxxxxxxxxxx

令牌按会话存储（由 mcp-session-id 头标识），并在同一会话中的后续请求中重复使用。

使用 Cursor 的远程授权客户端配置示例

{
  "mcpServers": {
    "GitLab": {
      "url": "http(s)://<your_mcp_gitlab_server>/mcp",
      "headers": {
        "Authorization": "Bearer glpat-..."
      }
    }
  }
}

重要提示：

• 远程授权 仅适用于可流式 HTTP 传输
• 每个会话是隔离的——一个会话中的令牌无法访问另一个会话的数据。会话关闭时，令牌会自动清除。
• 会话超时： 认证令牌在不活动 SESSION_TIMEOUT_SECONDS（默认 1 小时）后失效。超时后，客户端必须重新发送认证头信息。传输会话仍然保持活跃。
• 每次请求都会重置该会话的超时计时器。
• 速率限制： 每个会话每分钟的请求次数受限于 MAX_REQUESTS_PER_MINUTE（默认 60 次）。
• 容量限制： 服务器最多接受 MAX_SESSIONS 个并发会话（默认 1000 个）。

MCP OAuth 设置（Claude.ai 原生 OAuth）

当使用 GITLAB_MCP_OAUTH=true 时，服务器会充当您 GitLab 实例的 OAuth 代理。Claude.ai（以及任何符合 MCP 规范的客户端）会自动处理整个浏览器认证流程——无需手动管理个人访问令牌。

先决条件：

需要一个预先注册的 GitLab OAuth 应用程序。GitLab 会将动态注册的（未验证的）应用程序限制在 mcp 范围内，而这个范围不足以进行 API 调用（需要 api 或 read_api）。

1. 前往您的 GitLab 实例 → 管理员区域 > 应用程序（实例级别）或 用户设置 > 应用程序（个人级别）
2. 创建一个新的应用程序，配置如下：
   • 保密性：取消勾选
   • 作用域：api、read_api、read_user（或者您打算通过 GITLAB_OAUTH_SCOPES 请求的其他作用域）
3. 保存并复制应用 ID——这就是您的 GITLAB_OAUTH_APP_ID

工作原理：

1. 用户在 Claude.ai 中添加您的 MCP 服务器 URL
2. Claude.ai 通过 /.well-known/oauth-authorization-server 发现 OAuth 端点
3. Claude.ai 通过动态客户端注册（POST /register）自行注册——由 MCP 服务器本地处理（每个客户端都会获得一个虚拟客户端 ID）
4. Claude.ai 使用预先注册的 OAuth 应用程序将用户的浏览器重定向到 GitLab 的登录页面
5. 用户完成身份验证；GitLab 重定向回 https://claude.ai/api/mcp/auth_callback
6. Claude.ai 在每次 MCP 请求中发送 Authorization: Bearer <token>
7. 服务器向 GitLab 验证该令牌，并将其按会话存储

服务器设置：

docker run -d \
  -e STREAMABLE_HTTP=true \
  -e GITLAB_MCP_OAUTH=true \
  -e GITLAB_OAUTH_APP_ID="your-gitlab-oauth-app-client-id" \
  -e GITLAB_API_URL="https://gitlab.example.com/api/v4" \
  -e MCP_SERVER_URL="https://your-mcp-server.example.com" \
  -p 3002:3002 \
  zereight050/gitlab-mcp

对于本地开发（允许 HTTP）：

MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL=true \
STREAMABLE_HTTP=true \
GITLAB_MCP_OAUTH=true \
GITLAB_OAUTH_APP_ID=your-gitlab-oauth-app-client-id \
MCP_SERVER_URL=http://localhost:3002 \
GITLAB_API_URL=https://gitlab.com/api/v4 \
node build/index.js

Claude.ai 配置：

{
  "mcpServers": {
    "GitLab": {
      "url": "https://your-mcp-server.example.com/mcp"
    }
  }
}

无需 headers 字段——Claude.ai 会自动通过 OAuth 获取令牌。

环境变量：

变量	必需	描述
GITLAB_MCP_OAUTH	是	设置为 true 以启用
GITLAB_OAUTH_APP_ID	是	预先注册的 GitLab OAuth 应用程序的客户端 ID
MCP_SERVER_URL	是	您的 MCP 服务器的公共 HTTPS URL
GITLAB_API_URL	是	您的 GitLab 实例的 API URL（例如 https://gitlab.com/api/v4）
STREAMABLE_HTTP	是	必须为 true（不支持 SSE）
GITLAB_OAUTH_SCOPES	否	要求的 GitLab 作用域，用逗号分隔（例如 api,read_user）。默认为 api（或当 GITLAB_READ_ONLY_MODE=true 时为 read_api）。预先注册的应用程序必须至少配置这些作用域。
MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL	否	仅用于本地 HTTP 开发时设置为 true

重要提示：

• MCP OAuth 仅适用于 Streamable HTTP 传输（SSE=true 不兼容）
• 每个用户会话都会存储自己的 OAuth 令牌——会话之间完全隔离
• 会话超时、速率限制和容量限制与 REMOTE_AUTHORIZATION 模式相同（SESSION_TIMEOUT_SECONDS、MAX_REQUESTS_PER_MINUTE、MAX_SESSIONS）
• 头部认证回退： 当请求头中存在 Private-Token 或 JOB-TOKEN 时，会跳过 OAuth 验证，直接使用原始令牌作为该会话的授权凭证。这使得 PAT 和 CI 作业令牌可以与 OAuth 流程在同一服务器实例上共存。Authorization: Bearer 始终被视为 OAuth 令牌——如果需要基于 PAT 的头部认证，请使用 Private-Token。

工具 🛠️

点击展开

1. merge_merge_request - 合并 GitLab 项目中的合并请求
2. create_or_update_file - 在 GitLab 项目中创建或更新单个文件
3. search_repositories - 搜索 GitLab 项目
4. create_repository - 创建一个新的 GitLab 项目
5. get_file_contents - 获取 GitLab 项目中文件或目录的内容
6. push_files - 将多个文件一次性提交到 GitLab 项目
7. create_issue - 在 GitLab 项目中创建新问题
8. create_merge_request - 在 GitLab 项目中创建新的合并请求
9. fork_repository - 将 GitLab 项目 fork 到您的账户或指定的命名空间
10. create_branch - 在 GitLab 项目中创建新分支
11. get_merge_request - 获取合并请求的详细信息，包括精简的部署摘要、落后提交数、提交添加摘要和批准摘要（必须提供 mergeRequestIid 或 branchName）
12. get_merge_request_diffs - 获取合并请求的更改/差异（必须提供 mergeRequestIid 或 branchName）
13. list_merge_request_diffs - 分页列出合并请求的差异（必须提供 mergeRequestIid 或 branchName）
14. get_merge_request_conflicts - 获取 GitLab 项目中合并请求的冲突
15. list_merge_request_changed_files - 代码审查流程的第一步。仅返回合并请求中更改的文件路径列表——不包含差异内容。请先调用此接口获取文件路径，再使用 get_merge_request_file_diff 以批量方式获取多个文件的差异（建议每次调用 3-5 个文件）。支持使用正则表达式进行 excluded_file_patterns 过滤。（必须提供 mergeRequestIid 或 branchName）
16. get_merge_request_file_diff - 代码审查流程的第二步。获取合并请求中一个或多个文件的差异。请先调用 list_merge_request_changed_files，然后将文件路径数组传递给该接口，以高效地获取差异。支持批量处理多个文件（建议每次 3-5 个）。（必须提供 mergeRequestIid 或 branchName）
17. list_merge_request_versions - 列出合并请求的所有版本
18. get_merge_request_version - 获取合并请求的特定版本
19. get_branch_diffs - 获取 GitLab 项目中两个分支或提交之间的更改/差异
20. update_merge_request - 更新合并请求（必须提供 mergeRequestIid 或 branchName）
21. create_note - 为问题或合并请求创建新评论
22. create_merge_request_thread - 在合并请求上创建新讨论线程
23. mr_discussions - 列出合并请求的讨论项
24. resolve_merge_request_thread - 解决合并请求上的讨论线程
25. update_merge_request_note - 修改现有的合并请求讨论笔记
26. create_merge_request_note - 向现有合并请求讨论线程添加新笔记
27. delete_merge_request_discussion_note - 删除合并请求上的讨论笔记
28. update_merge_request_discussion_note - 更新合并请求上的讨论笔记
29. create_merge_request_discussion_note - 向现有合并请求讨论线程添加新讨论笔记
30. delete_merge_request_note - 删除现有的合并请求笔记
31. get_merge_request_note - 获取合并请求的特定笔记
32. get_merge_request_notes - 列出合并请求的笔记
33. get_draft_note - 获取合并请求中的单个草稿笔记
34. list_draft_notes - 列出合并请求中的草稿笔记
35. create_draft_note - 为合并请求创建草稿笔记
36. update_draft_note - 更新现有的草稿笔记
37. delete_draft_note - 删除草稿笔记
38. publish_draft_note - 发布单个草稿笔记
39. bulk_publish_draft_notes - 发布合并请求的所有草稿笔记
40. list_merge_requests - 全局或在特定 GitLab 项目中列出合并请求，并提供过滤选项（project_id 现在是可选的）
41. approve_merge_request - 批准合并请求（需要相应权限）
42. unapprove_merge_request - 取消之前批准的合并请求
43. get_merge_request_approval_state - 获取合并请求的批准详情，包括批准人（优先使用 approval_state，否则回退到 approvals）
44. update_issue_note - 修改现有的问题讨论笔记
45. create_issue_note - 向现有问题讨论线程添加新笔记
46. list_issues - 列出问题（默认仅显示当前用户创建的问题；使用 scope='all' 可查看所有可访问的问题）
47. my_issues - 列出分配给已认证用户的这些问题（默认为未解决的问题）
48. get_issue - 获取 GitLab 项目中特定问题的详细信息
49. update_issue - 更新 GitLab 项目的某个问题
50. delete_issue - 从 GitLab 项目中删除一个问题
51. list_issue_links - 列出特定问题的所有关联问题
52. list_issue_discussions - 列出 GitLab 项目中某个问题的讨论
53. get_issue_link - 获取特定问题链接
54. create_issue_link - 在两个问题之间创建关联
55. delete_issue_link - 删除问题关联
56. list_namespaces - 列出当前用户可用的所有命名空间
57. get_namespace - 根据 ID 或路径获取命名空间的详细信息
58. verify_namespace - 验证命名空间路径是否存在
59. get_project - 获取特定项目的详细信息
60. list_projects - 列出当前用户可访问的所有项目
61. list_project_members - 列出 GitLab 项目的成员
62. list_group_projects - 列出 GitLab 组中的项目，并提供过滤选项
63. list_group_iterations - 列出组迭代，并提供过滤选项
64. list_labels - 列出项目的标签
65. get_label - 获取项目中的单个标签
66. create_label - 在项目中创建新标签
67. update_label - 更新项目中的现有标签
68. delete_label - 从项目中删除标签
69. list_pipelines - 列出 GitLab 项目中的流水线，并提供过滤选项
70. get_pipeline - 获取 GitLab 项目中特定流水线的详细信息
71. list_pipeline_jobs - 列出特定流水线中的所有作业
72. list_pipeline_trigger_jobs - 列出特定流水线中触发下游流水线的所有触发作业（桥接作业）
73. get_pipeline_job - 获取 GitLab 流水线作业的详细信息
74. get_pipeline_job_output - 获取 GitLab 流水线作业的输出/跟踪日志，可选择分页以限制上下文窗口的使用
75. create_pipeline - 为分支或标签创建新流水线
76. retry_pipeline - 重试失败或取消的流水线
77. cancel_pipeline - 取消正在运行的流水线
78. play_pipeline_job - 手动运行流水线作业
79. retry_pipeline_job - 重试失败或取消的流水线作业
80. cancel_pipeline_job - 取消正在运行的流水线作业
81. list_deployments - 列出 GitLab 项目中的部署，并提供过滤选项
82. get_deployment - 获取 GitLab 项目中特定部署的详细信息
83. list_environments - 列出 GitLab 项目中的环境
84. get_environment - 获取 GitLab 项目中特定环境的详细信息
85. list_job_artifacts - 列出作业工件归档中的文件，返回文件名、路径、类型和大小
86. download_job_artifacts - 下载作业的整个工件归档（zip 文件）到本地路径，并返回保存的文件路径
87. get_job_artifact_file - 根据文件在归档中的路径，获取作业工件中的单个文件内容
88. list_milestones - 列出 GitLab 项目中的里程碑，并提供过滤选项
89. get_milestone - 获取特定里程碑的详细信息
90. create_milestone - 在 GitLab 项目中创建新里程碑
91. edit_milestone - 编辑 GitLab 项目中的现有里程碑
92. delete_milestone - 从 GitLab 项目中删除里程碑
93. get_milestone_issue - 获取与特定里程碑相关的问题
94. get_milestone_merge_requests - 获取与特定里程碑相关的合并请求
95. promote_milestone - 将里程碑推进到下一阶段
96. get_milestone_burndown_events - 获取特定里程碑的燃尽事件
97. list_wiki_pages - 列出 GitLab 项目中的维基页面
98. get_wiki_page - 获取特定维基页面的详细信息
99. create_wiki_page - 在 GitLab 项目中创建新维基页面
100. update_wiki_page - 更新 GitLab 项目中的现有维基页面
101. delete_wiki_page - 从 GitLab 项目中删除维基页面
102. list_group_wiki_pages - 列出 GitLab 组中的维基页面
103. get_group_wiki_page - 获取特定组维基页面的详细信息
104. create_group_wiki_page - 在 GitLab 组中创建新维基页面
105. update_group_wiki_page - 更新 GitLab 组中的现有维基页面
106. delete_group_wiki_page - 从 GitLab 组中删除维基页面
107. get_repository_tree - 获取 GitLab 项目的仓库树（列出文件和目录）
108. list_commits - 列出仓库提交，并提供过滤选项
109. get_commit - 获取特定提交的详细信息
110. get_commit_diff - 获取特定提交的更改/差异
111. list_releases - 列出项目的全部发布
112. get_release - 根据标签名称获取发布
113. create_release - 在 GitLab 项目中创建新发布
114. update_release - 更新 GitLab 项目中的现有发布
115. delete_release - 从 GitLab 项目中删除发布（不会删除关联的标签）
116. create_release_evidence - 为现有发布创建发布证据（仅限 GitLab Premium/Ultimate 版本）
117. download_release_asset - 根据资产直接路径下载发布资产文件
118. get_users - 根据用户名获取 GitLab 用户的详细信息
119. list_events - 列出当前已认证用户的全部事件
120. get_project_events - 列出指定项目中所有可见的事件
121. upload_markdown - 将文件上传到 GitLab 项目，用于 Markdown 内容
122. download_attachment - 根据密钥和文件名从 GitLab 项目中下载上传的文件
123. get_work_item - 获取单个工作项的完整详细信息，包括状态、层级关系（父级/子级）、类型、标签、负责人以及所有小部件
124. list_work_items - 列出项目中的工作项，并提供筛选条件（类型、状态、搜索、负责人、标签）。返回包含状态和层级信息的工作项
125. create_work_item - 创建新的工作项（问题、任务、事件、测试用例、史诗、关键结果、目标、需求、工单）。支持设置标题、描述、标签、负责人、权重、父级、健康状况、开始/截止日期、里程碑和保密级别
126. update_work_item - 更新工作项。可以修改标题、描述、标签、负责人、权重、状态、健康状况、父级层级、子级、开始/截止日期、里程碑、保密级别、关联项目以及自定义字段
127. convert_work_item_type - 将工作项转换为不同类型（例如，问题转为任务，任务转为事件）
128. list_work_item_statuses - 列出项目中某类工作项的可用状态。需要 GitLab Premium/Ultimate 版本，并支持自定义状态
129. list_custom_field_definitions - 列出项目中某类工作项的可用自定义字段定义。返回设置自定义字段所需的字段名称、类型和 ID
130. move_work_item - 将工作项（问题、任务等）移动到不同项目。使用 GitLab GraphQL issueMove 变更
131. list_work_item_notes - 列出工作项上的笔记和讨论。返回带有作者、正文、时间戳以及系统/内部标记的线程式讨论
132. create_work_item_note - 向工作项添加笔记/评论。支持 Markdown、内部笔记和线程式回复
133. get_timeline_events - 列出事件的时间线记录。返回按时间顺序排列的事件，附带笔记、时间戳和标签
134. create_timeline_event - 在事件上创建时间线事件。支持以下标签：“开始时间”、“结束时间”、“检测到影响”、“启动响应”、“影响减轻”、“查明原因”
135. list_webhooks - 列出 GitLab 项目或组中所有已配置的 Webhook。需提供 project_id 或 group_id
136. list_webhook_events - 列出项目或组 Webhook 的近期事件（过去 7 天）。可先使用概览模式查看，再调用 get_webhook_event 获取详细信息
137. get_webhook_event - 根据 ID 获取特定 Webhook 事件的完整详细信息，包括请求和响应负载
138. search_code - 在 GitLab 实例的所有项目中搜索代码（需要启用高级搜索或精确代码搜索功能）
139. search_project_code - 在特定 GitLab 项目中搜索代码（需要启用高级搜索或精确代码搜索功能）
140. search_group_code - 在特定 GitLab 组中搜索代码（需要启用高级搜索或精确代码搜索功能）
141. execute_graphql - 执行 GitLab GraphQL 查询

测试 🧪

该项目包含全面的测试覆盖，包括远程授权测试：

# 运行所有测试（API 验证 + 远程认证）
npm test

# 仅运行远程授权测试
npm run test:remote-auth

# 运行所有测试，包括只读 MCP 测试
npm run test:all

# 仅运行 API 验证
npm run test:integration

所有远程授权测试都使用模拟的 GitLab 服务器，无需真实的 GitLab 凭据。

GitLab MCP Server 快速上手指南

GitLab MCP (Model Context Protocol) Server 是一个连接 AI 助手（如 Claude Code、Cursor、Cline 等）与 GitLab API 的桥梁。本版本在原版基础上修复了已知问题并增加了动态 API URL 支持。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: 版本 18 或更高（推荐最新 LTS 版本）。
  • 检查命令：node -v
• npm: 随 Node.js 自动安装。
  • 国内加速建议：配置淘宝镜像源以提升安装速度。

  npm config set registry https://registry.npmmirror.com
  

• GitLab 账号权限:
  • 您需要一个有效的 GitLab 实例地址。
  • 个人访问令牌 (Personal Access Token): 具有 api 权限（用于读写操作）或 read_api 权限（仅只读）。
  • 或者配置好 OAuth2 应用（推荐用于更高安全性）。

2. 安装步骤

该工具无需全局安装，通常通过 npx 直接运行，或在 MCP 客户端配置中指定命令。

方式 A：直接在终端测试运行

您可以使用以下命令快速验证工具是否可用（需替换令牌和 URL）：

npx -y @zereight/mcp-gitlab --token=YOUR_GITLAB_TOKEN --api-url=https://gitlab.com/api/v4

方式 B：集成到 AI 编辑器 (以 VS Code / Cursor 为例)

大多数现代 AI 代码编辑器支持通过 mcp.json 配置文件加载服务。

1. 在项目根目录创建 .vscode/mcp.json 文件（或在全局配置中添加）。
2. 填入以下配置（推荐使用 Personal Access Token 模式，最简单快捷）：

{
  "servers": {
    "GitLab-MCP": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token_here",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "false",
        "USE_MILESTONE": "false",
        "USE_PIPELINE": "false"
      }
    }
  }
}

注意: 请将 your_gitlab_token_here 替换为您真实的 GitLab Personal Access Token。如果是私有化部署的 GitLab，请修改 GITLAB_API_URL。

方式 C：Docker 部署 (适合服务器端)

如果您希望在容器环境中运行，可以使用官方镜像：

docker run -i --rm \
  -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_READ_ONLY_MODE=false \
  zereight050/gitlab-mcp

3. 基本使用

配置完成后，重启您的 AI 助手（如 Cursor、Claude Desktop 或 VS Code Copilot），即可在对话中调用 GitLab 功能。

最简单的使用示例

假设您已正确配置了 Token 和 API URL，您可以在聊天窗口中直接输入自然语言指令：

场景 1：查询项目信息

"列出当前项目中最近的 5 个 Merge Request。"

场景 2：代码审查辅助

"读取 src/main.py 文件的内容，并检查是否有未处理的 TODO 标记。"

场景 3：流水线管理

"触发当前分支的 CI 流水线，并告诉我构建状态。" (注：需在配置中将 USE_PIPELINE 设为 true)

高级认证：OAuth2 (可选)

为了更安全地管理凭证（避免硬编码 Token），您可以配置 OAuth2。

1. 在 GitLab 创建应用:

   • 进入 Admin area → Applications。
   • Name: GitLab MCP Server
   • Redirect URI: http://127.0.0.1:8888/callback
   • Scopes: 勾选 api。
   • 保存并复制 Application ID。

2. 更新配置文件:

{
  "servers": {
    "GitLab-MCP": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_USE_OAUTH": "true",
        "GITLAB_OAUTH_CLIENT_ID": "your_application_id",
        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8888/callback",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

启动后，系统会自动打开浏览器引导您完成授权，令牌将安全存储在本地。