MCP GitLab CrunchTools

一个安全的 MCP（模型上下文协议）服务器，用于 GitLab 项目、合并请求、问题、流水线和搜索。适用于任何 GitLab 实例（gitlab.com、自托管或企业版）。

概述

此 MCP 服务器设计为：

• 默认安全 - 全面的威胁建模、输入验证和令牌保护

• 无第三方服务 - 通过 stdio 在本地运行，您的 API 令牌永远不会离开您的机器

• 多实例 - 通过可配置的 URL 支持 gitlab.com、自托管 GitLab 或企业实例

• 跨平台 - 支持 Linux、macOS 和 Windows

• 自动更新 - GitHub Actions 监控 CVE 并更新依赖

• 容器化 - 可在 quay.io/crunchtools/mcp-gitlab 获取，基于 Hummingbird Python 基础镜像构建

Related MCP server: gitlab-mcp-server

命名约定

为什么选择 Hummingbird？

容器镜像基于 Project Hummingbird 的 Hummingbird Python 基础镜像 构建，该镜像提供：

• 最小的 CVE 暴露 - 使用最小的软件包集构建，大幅减少攻击面

• 定期更新 - 及时应用安全补丁

• 针对 Python 优化 - 预配置的 Python 环境，使用 uv 包管理器

• 生产就绪 - 正确的信号处理和非 root 用户默认设置

功能

项目管理（5 个工具）

• list_projects - 列出项目，支持过滤和搜索

• get_project - 按 ID 或路径获取项目详情

• list_project_branches - 列出仓库分支

• get_project_branch - 获取单个分支

• list_project_commits - 列出提交，支持日期/路径过滤

组管理（3 个工具）

• list_groups - 列出组，支持过滤

• get_group - 按 ID 或路径获取组详情

• list_group_projects - 列出组中的项目（支持子组）

合并请求（7 个工具）

• list_merge_requests - 按状态、标签、里程碑列出 MR

• get_merge_request - 获取 MR 详情

• create_merge_request - 创建新的 MR

• update_merge_request - 更新 MR 标题、描述、状态、指派人员

• list_mr_notes - 列出 MR 上的评论

• create_mr_note - 向 MR 添加评论

• get_mr_changes - 获取 MR 的差异

问题（6 个工具）

• list_issues - 按状态、标签、里程碑、指派人员列出问题

• get_issue - 获取问题详情

• create_issue - 创建新问题

• update_issue - 更新问题标题、描述、状态、标签

• list_issue_notes - 列出问题上的评论

• create_issue_note - 向问题添加评论

流水线（4 个工具）

• list_pipelines - 列出 CI/CD 流水线，支持状态过滤

• get_pipeline - 获取流水线详情

• list_pipeline_jobs - 列出流水线中的作业

• get_job_log - 获取作业日志输出

搜索（2 个工具）

• search_global - 在所有可访问的 GitLab 资源中搜索

• search_project - 在特定项目中搜索

安装

使用 uvx（推荐）

uvx mcp-gitlab-crunchtools

使用 pip

pip install mcp-gitlab-crunchtools

使用容器

podman run -e GITLAB_TOKEN=your_token \
    quay.io/crunchtools/mcp-gitlab

配置

环境变量

创建 GitLab 个人访问令牌

1. 导航到访问令牌

   • 前往 https://gitlab.com/-/user_settings/personal_access_tokens

   • 或：头像 > 偏好设置 > 访问令牌

2. 创建自定义令牌

   • 名称：mcp-gitlab-crunchtools

   • 过期时间：设置适当的日期（建议 90 天）

   • 范围：根据您的需求选择范围

3. 范围选择

   范围	访问级别	功能
   read_api	只读	列出/查看项目、问题、MR、流水线
   api	完全访问	所有功能，包括创建/更新

4. 复制并存储令牌

   • 立即复制令牌（以 glpat- 开头）

   • 安全存储在密码管理器中

添加到 Claude Code

claude mcp add mcp-gitlab-crunchtools \
    --env GITLAB_TOKEN=your_token_here \
    -- uvx mcp-gitlab-crunchtools

对于自托管 GitLab：

claude mcp add mcp-gitlab-crunchtools \
    --env GITLAB_TOKEN=your_token_here \
    --env GITLAB_URL=https://gitlab.example.com \
    -- uvx mcp-gitlab-crunchtools

对于容器版本：

claude mcp add mcp-gitlab-crunchtools \
    --env GITLAB_TOKEN=your_token_here \
    -- podman run -i --rm -e GITLAB_TOKEN quay.io/crunchtools/mcp-gitlab

使用示例

列出您的项目

User: List my GitLab projects
Assistant: [calls list_projects with membership=true]

查看合并请求

User: Show open merge requests for my-org/backend
Assistant: [calls list_merge_requests with project_id="my-org/backend"]

创建问题

User: Create an issue in my-org/backend titled "Fix login timeout"
Assistant: [calls create_issue with title="Fix login timeout"]

检查流水线状态

User: Show failed pipelines for my-org/api
Assistant: [calls list_pipelines with status="failed"]

搜索代码

User: Search for "authentication" in my-org/backend
Assistant: [calls search_project with scope="blobs"]

安全

此服务器将安全作为首要关注点。请参阅 SECURITY.md 了解：

• 威胁模型和攻击向量

• 纵深防御架构

• 令牌处理最佳实践

• 输入验证规则

• 审计日志

关键安全功能

1. 令牌保护

   • 存储为 SecretStr（永远不会被意外记录）

   • 仅通过环境变量（绝不存储在文件或参数中）

   • 从所有错误消息中清理

2. 输入验证

   • 所有输入使用 Pydantic 模型

   • 项目和组 ID 的允许列表字符验证

   • 路径遍历防护

3. API 加固

   • 强制 HTTPS（localhost 除外）

   • TLS 证书验证

   • 请求超时（30 秒）

   • 响应大小限制（10MB）

4. 自动化 CVE 扫描

   • GitHub Actions 每周扫描依赖

   • 使用 Trivy 进行容器安全扫描

   • Python 的 CodeQL 分析

开发

设置

git clone https://github.com/crunchtools/mcp-gitlab.git
cd mcp-gitlab
uv sync

运行测试

uv run pytest

代码检查与类型检查

uv run ruff check src tests
uv run mypy src

构建容器

podman build -t mcp-gitlab .

许可证

AGPL-3.0-or-later

贡献

欢迎贡献！在提交与安全相关的更改之前，请阅读 SECURITY.md。

链接

• GitLab REST API 文档

• FastMCP 文档

• MCP 规范

• crunchtools.com