GitLab-MCP

作者：Adit-9997 星标更新：2025-05-21

项目介绍

GitLab MCP 服务器

这是一个用于与 GitLab API 交互的 MCP（模型上下文协议）服务器。该服务器提供了一组工具，允许AI客户端对 GitLab 仓库、问题、合并请求等进行操作。所有操作都支持同步和异步执行模式。

安装

使用 uv（推荐）

# 克隆仓库
git clone https://github.com/Adit-999/gitlab-mcp.git
cd gitlab-mcp

# 使用 uv 安装依赖
uv sync

使用 pip

# 克隆仓库
git clone https://github.com/Adit-999/gitlab-mcp.git
cd gitlab-mcp

# 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

# 安装依赖
pip install -e .

配置

GitLab MCP 服务器需要两个环境变量才能正常工作：

GITLAB_PERSONAL_ACCESS_TOKEN - 用于与 GitLab API 进行身份验证
GITLAB_API_URL - GitLab API 的基础 URL

方案 1：环境变量

在项目根目录创建一个 .env 文件，包含这些变量：

GITLAB_PERSONAL_ACCESS_TOKEN=your_personal_access_token
GITLAB_API_URL=https://gitlab.com

方案 2：MCP 配置

你也可以在你的 MCP JSON 配置文件中配置 MCP 服务器：

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "uv",
      "args": ["run", "--with", "mcp[cli]", "mcp", "run", "/path/to/gitlab-mcp/server.py"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_personal_access_token",
        "GITLAB_API_URL": "https://gitlab.com"
      }
    }
  }
}

使用 uv 配置 Claude Desktop

uv run mcp install server.py

项目结构

该项目遵循模块化、领域驱动的架构：

gitlab-mcp/
├── src/                           # 源代码
│   ├── api/                       # API 交互层
│   │   ├── rest_client.py         # GitLab REST API 客户端
│   │   ├── exceptions.py          # API 异常定义
│   ├── schemas/                   # 数据模型和验证
│   │   ├── base.py                # 基础模式类
│   │   ├── repositories.py        # 仓库数据模型
│   │   ├── branches.py            # 分支数据模型
│   │   ├── issues.py              # 问题数据模型
│   │   ├── merge_requests.py      # 合并请求数据模型
│   │   ├── groups.py              # 组数据模型
│   │   └── search.py              # 搜索数据模型
│   ├── services/                  # 业务逻辑层
│   │   ├── repositories.py        # 仓库操作
│   │   ├── branches.py            # 分支操作
│   │   ├── issues.py              # 问题操作
│   │   ├── merge_requests.py      # 合并请求操作
│   │   ├── groups.py              # 组操作
│   │   └── search.py              # 搜索操作
│   └── tools/                     # MCP 工具实现
│       ├── repositories.py        # 仓库工具
│       ├── branches.py            # 分支工具
│       ├── issues.py              # 问题工具
│       ├── merge_requests.py      # 合并请求工具
│       ├── groups.py              # 组工具
│       └── search.py              # 搜索工具
├── server.py                      # 主 MCP 服务器入口点

这种架构提供了以下好处：

关注分离：每个模块都有明确的责任
类型安全：Pydantic 模式确保数据验证
可维护性：领域驱动组织使代码更容易导航
可扩展性：通过遵循已建立的模式添加新功能
异步支持：所有操作都可用同步和异步版本

可用工具

服务器提供了以下工具来与 GitLab 交互：

仓库管理

create_repository：创建一个新的 GitLab 仓库
list_repository_tree：列出仓库树的内容

分支操作

create_branch：在 GitLab 仓库中创建一个新的分支
list_branches：列出 GitLab 仓库中的分支
get_branch：获取特定 GitLab 分支的详细信息
delete_branch：从 GitLab 仓库中删除一个分支
delete_merged_branches：从 GitLab 仓库中删除所有已合并的分支
protect_branch：保护 GitLab 仓库中的一个分支
unprotect_branch：取消 GitLab 仓库中一个分支的保护
get_default_branch_ref：获取 GitLab 仓库的默认分支引用

文件操作

create_file：在 GitLab 仓库中创建一个新的文件
get_file_contents：从 GitLab 仓库中检索文件内容
update_file：更新 GitLab 仓库中的现有文件
delete_file：从 GitLab 仓库中删除一个文件

问题管理

create_issue：在 GitLab 仓库中创建一个新的问题
list_all_issues：列出认证用户有权访问的所有问题
get_issue：获取特定 GitLab 问题的详细信息
close_issue：关闭 GitLab 问题
delete_issue：从 GitLab 仓库中删除一个问题
move_issue：将问题移动到不同的项目
comment_on_issue：向 GitLab 问题添加评论
list_issue_comments：列出 GitLab 问题的评论

合并请求操作

create_merge_request：在 GitLab 仓库中创建一个新的合并请求
list_merge_requests：列出 GitLab 项目的合并请求
get_merge_request：获取特定 GitLab 合并请求的详细信息
merge_merge_request：合并 GitLab 合并请求
update_merge_request：更新 GitLab 仓库中的现有合并请求
delete_merge_request：从 GitLab 仓库中删除一个合并请求
merge_request_changes：获取特定合并请求的更改
create_merge_request_comment：向 GitLab 合并请求添加评论

作业操作

get_job_logs：获取 GitLab 作业的日志

组操作

list_groups：列出 GitLab 组
get_group：获取特定 GitLab 组
get_group_by_project_namespace：根据项目命名空间获取 GitLab 组

搜索工具

search_globally：搜索所有 GitLab 资源（当前支持项目和文件/块）
search_project：在特定项目内搜索（当前支持项目和文件/块）
search_group：在特定组内搜索（当前支持项目和文件/块）

故障排除

常见问题

GitLab API 认证错误：确保你的 GITLAB_PERSONAL_ACCESS_TOKEN 具有必要的权限，并且正确设置在环境变量中。
NoneType 错误：某些函数在处理空结果时可能会遇到问题。如果你遇到这些错误，请报告详细的重现步骤。

许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。