mcp-gitlab

mcp-gitlab

mcp-gitlab 是一个面向 GitLab REST API 的 Model Context Protocol (MCP) 服务。它为 AI 助手提供 91 个工具、7 个资源和 6 个提示词，用于管理项目、合并请求、流水线、CI/CD 变量、审批、议题和代码审查。适用于 Claude Desktop、Claude Code、Cursor、Windsurf、VS Code Copilot，以及任何兼容 MCP 的客户端。支持两种运行模式：允许写入，或锁定为只读模式（MCP_READ_ONLY=true），这样模型就不会获得 57 个写入工具。

支持 GitLab.com 和自托管的 GitLab 实例（CE/EE）。无需 GitLab Duo 或 Premium。

支持 MCP 2026-07-28 规范（通常称为 MCP 2.0），并兼容 2025-11-25 客户端。

基于 FastMCP 4.x、httpx 和 Pydantic 构建。

安装： uvx mcp-gitlab | PyPI | MCP Registry | 更新日志

uvx mcp-gitlab                          # with writes
MCP_READ_ONLY=true uvx mcp-gitlab       # locked read-only: write tools are not listed

一键安装

💡 提示： 其他 AI 助手（Claude Code、Windsurf、IntelliJ、Gemini CLI）的安装方法，请访问 GitLab MCP 安装入口。

# with writes
claude mcp add gitlab -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx -- uvx mcp-gitlab
# locked read-only
claude mcp add gitlab -e MCP_READ_ONLY=true -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx -- uvx mcp-gitlab

{
  "mcpServers": {
    "gitlab": {
      "command": "uvx",
      "args": ["mcp-gitlab"],
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "MCP_READ_ONLY": "true"
      }
    }
  }
}

# with writes
gemini mcp add -s user -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx gitlab uvx mcp-gitlab
# locked read-only
gemini mcp add -s user -e MCP_READ_ONLY=true -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx gitlab uvx mcp-gitlab

{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-gitlab"],
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "MCP_READ_ONLY": "true"
      }
    }
  }
}

# with writes
codex mcp add gitlab --env GITLAB_URL=https://gitlab.example.com --env GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx -- uvx mcp-gitlab
# locked read-only
codex mcp add gitlab --env MCP_READ_ONLY=true --env GITLAB_URL=https://gitlab.example.com --env GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx -- uvx mcp-gitlab

uv pip install mcp-gitlab

支持的令牌类型

服务按顺序检查这些环境变量——采用第一个匹配项：

1. GITLAB_TOKEN
2. GITLAB_PAT
3. GITLAB_PERSONAL_ACCESS_TOKEN
4. GITLAB_API_TOKEN

这些变量接受以下任意令牌类型：

无令牌登录

当你通过 stdio 为自己运行服务且没有个人访问令牌时，可使用此方式。mcp-gitlab auth login 会将你登录到 GitLab，作为公共 OAuth 客户端，并在本地存储令牌。服务随后会在启动时读取令牌，并自行刷新。这不是 OAuth 模式；服务仍处于令牌模式，MCP 通信线路上的内容也不会改变。

三个命令：

mcp-gitlab auth login     # device flow by default; add --web for the browser flow
mcp-gitlab auth status    # show the stored account, scopes, and token freshness
mcp-gitlab auth logout    # revoke the token at GitLab and delete the local copy

auth login 会输出一个代码和一个 URL。打开该 URL，输入代码并批准。随后只需设置 GITLAB_URL，无需令牌，服务即可运行。

客户端 ID

每次登录都需要 OAuth 应用 ID。解析顺序为：--client-id，然后是 GITLAB_OAUTH_CLIENT_ID，最后是 https://gitlab.com 的内置默认值。

gitlab.com 的默认值尚未注册。在注册之前，gitlab.com 也需要设置 GITLAB_OAUTH_CLIENT_ID 或传入 --client-id。

注册应用（自管理实例，或默认值发布前的 gitlab.com）

在 用户设置 → 应用程序 → 添加新应用程序 下创建应用，并使用以下设置：

请使用 127.0.0.1，不要使用 localhost。设备授权流程需要 GitLab 17.9 或更高版本；较旧的实例请使用 mcp-gitlab auth login --web。

存储与优先级

凭据存储在 ~/.config/mcp-gitlab/credentials.json 中，每个 GitLab URL 对应一个条目，权限模式为 0600。环境令牌始终优先：如果设置了 GITLAB_TOKEN，服务会使用它并忽略存储的凭据。

传入 --scopes read_api 可启用只读会话；随后服务会在进行任何 API 调用之前阻止写入工具。

OAuth 2.1（远程部署）

对于由多人共用的服务，--auth oauth 会将 mcp-gitlab 设为 MCP 2026-07-28 资源服务器，并以 GitLab 作为上游 OAuth 提供方：每位用户都使用自己的 GitLab 账户登录，每个请求都使用该用户的令牌运行，服务器上无需配置个人访问令牌。适用于只托管一次服务器、由多位用户连接的场景；单用户本地设置请保留默认的 --auth token。

OAuth 模式需要 --transport streamable-http（OAuth 仅适用于 HTTP；stdio 仍使用环境令牌）。

1. 注册 GitLab OAuth 应用程序（用户设置 → 应用程序，或群组／实例应用程序）。将重定向 URI 设为 <base>/auth/callback（例如 https://mcp.example.com/auth/callback），标记为机密，并授予 api 作用域（只读部署可使用 read_api）。复制应用程序 ID 和密钥。

2. 配置服务：

GITLAB_URL=https://gitlab.com GITLAB_AUTH=oauth \
  GITLAB_OAUTH_CLIENT_ID=... GITLAB_OAUTH_CLIENT_SECRET=... \
  GITLAB_OAUTH_BASE_URL=https://mcp.example.com \
  uvx mcp-gitlab --transport streamable-http

将 MCP 客户端（或 MCP Inspector，pnpm dlx @modelcontextprotocol/inspector）指向 <base>/mcp；客户端会发现授权服务器并运行 OAuth 流程，之后每次工具调用都会使用该用户的 GitLab 令牌。仅具备 read_api 的令牌可以读取，但写入请求会被拒绝，并提供可执行的提示。

完整指南、客户端设置和故障排除：docs/oauth.md。

兼容性

协议支持

mcp-gitlab 实现了模型上下文协议（Model Context Protocol）。它支持 2026-07-28 规范，通常称为 MCP 2.0，并兼容 2025-11-25 客户端。

• 规范：MCP 2026-07-28（MCP 2.0）。已通过 stdio 和 streamable-http 验证。
• 旧版客户端：2025-11-25 客户端仍可使用。
• 基于：FastMCP 4.x 和 MCP Python SDK 2.x。
• 传输方式：stdio（默认）和 streamable-http（远程连接推荐）。sse（HTTP+SSE）传输仍可使用，但 2026-07-28 规范已将其弃用。使用时，服务会打印警告。
• 功能：工具、资源和提示词。服务不使用 roots、sampling、logging、elicitation 或资源订阅，因此 2026-07-28 的弃用不会影响它。

错误结果

预期中的失败（404、401、验证错误，或触发只读保护的写入操作）会作为工具结果返回，并设置协议级别的 isError 标志，因此客户端可以检测到错误并自行纠正，而不必从原本成功的结果中解析 "error" 键。在锁定的只读模式下，写入工具会被隐藏，因此调用这类工具会返回 Unknown tool 错误；只读封装是保护机制自身的响应，仅当客户端仍然调用了写入工具时才会返回（例如，客户端使用了缓存的工具列表，或未来出现了未标记的工具）。响应正文是包含 error，以及在有帮助时还包含 status_code、body 和可执行 hint 的 JSON 对象。该对象就是结果的文本内容；错误不会设置 structuredContent，因为严格客户端（TypeScript MCP SDK）即使在 isError 结果中也会根据工具的输出架构验证 structuredContent，而该架构会拒绝错误正文。意外错误同样会设置 isError，但只包含 TypeName: message 文本，也不会设置 structuredContent。

成功的结果会在美化后的文本内容和 structuredContent 中都以 JSON 对象形式携带响应（即对象本身，而不是严格客户端会拒绝的旧版 {"result": "<json string>"} 封装）。工具不会声明 outputSchema：上游 GitLab 字段会以无类型形式传递，因此新增 API 字段不会导致架构校验失败；如果客户端需要类型化架构，可通过每个工具的 output_schema= 选择启用。

工具（91）

资源（7）

该服务将精心整理的工作流指南作为 MCP 资源提供，客户端可按需读取。

提示词（6）

该服务提供 MCP 提示词——可复用的多工具工作流模板，客户端可将其显示为斜杠命令。

使用示例

项目与分支

"Get details for project my-org/api-gateway"
→ gitlab_get_project(project_id="my-org/api-gateway")

"Create a feature branch from main"
→ gitlab_create_branch(project_id="123", branch_name="feat/login", ref="main")

"Delete all branches merged into main"
→ gitlab_list_branches(project_id="123") → filter merged → gitlab_delete_branch for each

合并请求与代码审查

"Open a merge request from feat/login to main"
→ gitlab_create_mr(project_id="123", source_branch="feat/login", target_branch="main", title="Add login")

"Review MR !42 — list changes and add inline comments"
→ gitlab_mr_changes(project_id="123", mr_iid=42)
→ gitlab_create_mr_discussion(project_id="123", mr_iid=42, body="nit: ...", new_path="src/auth.py", new_line=15)
  # old_line is filled from the diff when line 15 is unchanged

"Merge MR !42 after resolving all threads"
→ gitlab_list_mr_discussions(project_id="123", mr_iid=42) → resolve unresolved
→ gitlab_merge_mr(project_id="123", mr_iid=42, squash=True)

流水线与 CI/CD

"Show failed pipelines on main this week"
→ gitlab_list_pipelines(project_id="123", ref="main", status="failed")

"Retry a failed pipeline"
→ gitlab_retry_pipeline(project_id="123", pipeline_id=456)

"Get the build log for job 789"
→ gitlab_get_job_log(project_id="123", job_id=789, tail_lines=100)

问题

"Create a bug report in project 123"
→ gitlab_create_issue(project_id="123", title="Login page 500 error", labels=["bug","P1"])

"Find open issues assigned to me"
→ gitlab_list_issues(project_id="123", state="opened", assignee_username="johndoe")

安全注意事项

• 令牌范围：使用所需的最小范围。api 范围授予完整访问权限；只读部署优先使用 read_api。
• 只读模式：在你控制的启动配置中设置 MCP_READ_ONLY=true（或 GITLAB_READ_ONLY=true），服务启动后便会锁定：57 个写入工具和写入工作流提示词不会列出，调用这些工具会返回 "Unknown tool"，而防护机制会拒绝任何仍然到达服务的写入操作。运行时无法解除锁定——无论是其他来源提供的 false、.env 文件还是工具参数都不行；任何不是 false/0/no/off/空值的值都会锁定，而 --read-only 只能加强锁定。锁定强度取决于启动配置：应在用户无法编辑的位置设置，例如托管的 MCP 配置（如 Claude Code managed-mcp.json）、容器、k8s 或 systemd 环境，或托管的 HTTP 部署。自行启动服务的用户可以控制其环境。在 OAuth 模式下，还应设置 GITLAB_OAUTH_SCOPES=read_api，使每位用户的 GitLab 令牌都不具备写入范围。
• SSL 验证：默认值为 GITLAB_SSL_VERIFY=true。仅在可信网络中使用自签名证书时才禁用。
• CI/CD 变量遮蔽：gitlab_list_variables 和 gitlab_list_group_variables 会自动遮蔽 GitLab 中标记为已遮蔽的变量值，并返回 ***MASKED***，而非实际值。
• MCP 工具注释：每个工具都会声明 readOnlyHint、destructiveHint 和 idempotentHint，供客户端显示权限提示。
• 凭据存储：服务从环境中读取 GITLAB_TOKEN，且绝不会写入该值。mcp-gitlab auth login 会将 OAuth 令牌存储在 ~/.config/mcp-gitlab/credentials.json（模式为 0600）中，并在原位置刷新令牌。

速率限制与权限

速率限制

GitLab 会对每位用户实施速率限制（已认证用户默认每分钟 2000 次请求）。触发速率限制时，工具会返回 429 错误，并提示等待后重试。分页端点每页默认返回 20 条结果；使用 per_page（最大值为 100）可减少 API 调用次数。

所需权限

CLI 与传输选项

# Default: stdio transport (for MCP clients)
uvx mcp-gitlab

# HTTP transport — streamable-http is recommended for remote use
uvx mcp-gitlab --transport streamable-http --port 9000

# SSE transport — deprecated by MCP 2026-07-28; still works, prints a warning
uvx mcp-gitlab --transport sse --host 127.0.0.1 --port 8000

# OAuth 2.1 mode (per-user GitLab sign-in; streamable-http only) — see "OAuth 2.1" above
uvx mcp-gitlab --auth oauth --transport streamable-http

# Local sign-in for stdio without a token — see "Sign in without a token" above
mcp-gitlab auth login|status|logout

# CLI overrides for config
GITLAB_TOKEN=glpat-xxx uvx mcp-gitlab --gitlab-url https://gitlab.example.com --read-only

--gitlab-token 仍可使用，但已弃用并从 --help 中隐藏：它会将令牌暴露在 ps 和 Shell 历史记录中。请使用 GITLAB_TOKEN。

--auth {token,oauth} 用于选择身份验证模式（默认值为 token）； oauth 需要 --transport streamable-http。

在 token 模式下，HTTP 传输会使用唯一的 GITLAB_TOKEN 向任何能够访问该端口的人提供所有工具，因此除非设置 GITLAB_HTTP_BEARER_TOKEN（至少 16 个字符；客户端通过 Authorization: Bearer <token> 发送）或切换到 --auth oauth 进行逐用户登录，否则服务会拒绝绑定到非环回的 --host。 默认绑定地址 127.0.0.1 无需上述设置。

服务会通过 python-dotenv 自动从工作目录加载 .env 文件。

Docker

精简的非 root 镜像可直接从此仓库构建（uv、已提交的 uv.lock）。镜像默认锁定为只读模式（MCP_READ_ONLY=true）；覆盖此设置即可允许写入。

docker build -t mcp-gitlab .

# locked read-only (the image default) — stdio for an MCP client
docker run --rm -i \
  -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx \
  mcp-gitlab

# allow writes: override the read-only default
docker run --rm -i \
  -e MCP_READ_ONLY=false \
  -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx \
  mcp-gitlab

对于 HTTP 传输，追加 --transport streamable-http --host 0.0.0.0；在 token 模式下绑定到非环回地址需要设置 GITLAB_HTTP_BEARER_TOKEN（至少 16 个字符）或 GITLAB_AUTH=oauth（见上文）。

常见问题

mcp-gitlab 支持 MCP 2.0 吗？

支持。它符合 MCP 2026-07-28 规范，该规范通常称为 MCP 2.0。它也继续兼容 2025-11-25 客户端。

它能与可自托管的 GitLab 配合使用吗？

可以。它适用于 GitLab.com 和可自托管的 GitLab（CE 和 EE）。它不需要 GitLab Duo 或 Premium。

它支持哪些传输方式？

它支持 stdio（默认）和 streamable-http。sse 传输方式仍然可用，但 2026-07-28 规范已将其弃用。OAuth 2.1 模式（--auth oauth）仅适用于 streamable-http。

我可以以只读模式运行 mcp-gitlab，让助手无法合并、推送或评论吗？

可以。使用 MCP_READ_ONLY=true（或 GITLAB_READ_ONLY=true）启动它。此时，57 个写入工具和写入工作流提示词都不会列出，因此模型看不到它们；调用这些工具会返回“Unknown tool”，且进程运行期间无法重新启用写入功能。请在由你控制的启动配置中设置此变量，例如托管的 MCP 配置、容器或 systemd 环境变量，或者托管部署；因为自行启动服务的用户可以不设置此变量。

它需要哪些令牌权限范围？

如需完整访问权限，请使用具有 api 权限范围的令牌。只读部署请使用具有 read_api 权限范围的令牌。服务会从环境变量读取 GITLAB_TOKEN，且不会写入该变量；通过 mcp-gitlab auth login 获取的令牌会存储在 ~/.config/mcp-gitlab/credentials.json 中。

它适用于哪些 AI 助手？

它适用于 Claude Desktop、Claude Code、Cursor、Windsurf、VS Code Copilot，以及任何兼容 MCP 的客户端。

如何安装 mcp-gitlab？

运行 uvx mcp-gitlab，或将它添加到 MCP 客户端配置中。请参阅上文的安装部分。

相关 MCP 服务

• mcp-atlassian-extended — Jira + Confluence 集成（22 个工具、15 个资源、5 个提示词）
• mcp-coda — Coda 集成（53 个工具、12 个资源、5 个提示词）
• mcp-argocd — Argo CD 集成（37 个工具、7 个资源、7 个提示词）

开发

git clone https://github.com/vish288/mcp-gitlab.git
cd mcp-gitlab
uv sync --all-extras

uv run pytest --cov
uv run ruff check .
uv run ruff format --check .

许可证

MIT