MCP Gitlab

MCP GitLab CrunchTools

一个安全的 MCP（Model Context Protocol）服务，适用于 GitLab 项目、合并请求、议题、流水线和搜索。支持任何 GitLab 实例（gitlab.com、自托管或企业版）。

概览

此 MCP 服务旨在实现：

• 默认安全 - 提供有文档说明的威胁模型（参见 SECURITY.md）、Pydantic 输入验证，并将 API 令牌存储为 SecretStr，以防意外记录到日志中
• 无需第三方服务 - 通过 stdio 在本地运行，API 令牌绝不会离开你的设备
• 支持多实例 - 通过可配置的 URL 支持 gitlab.com、自托管 GitLab 或企业版实例
• 跨平台 - 支持 Linux、macOS 和 Windows
• 自动更新 - GitHub Actions 监控 CVE 并更新依赖项
• 容器化 - 可通过 quay.io/crunchtools/mcp-gitlab 获取，该容器基于 Hummingbird Python 基础镜像构建

命名约定

组件	名称
GitHub 仓库	crunchtools/mcp-gitlab
容器	quay.io/crunchtools/mcp-gitlab
Python 包（PyPI）	mcp-gitlab-crunchtools
CLI 命令	mcp-gitlab-crunchtools
模块导入	mcp_gitlab_crunchtools

为什么选择 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_TOKEN	是	—	个人访问令牌
GITLAB_URL	否	https://gitlab.com	GitLab 实例 URL
SSL_CERT_FILE	否	—	自定义 CA 证书包路径，适用于使用内部 CA 的自托管 GitLab
GITLAB_SSL_VERIFY	否	true	设置为 false 可禁用 TLS 验证（不推荐）

创建 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 证书
   • 请求超时（30s）
   • 响应大小限制（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