GitLab版本控制工具

你是否曾经希望AI能够直接操作你的GitLab仓库，自动创建项目、管理合并请求、处理Issue，甚至批量操作文件？今天要介绍的开源项目GitLab版本控制工具，正是为了实现这个目标而设计的。它由模型上下文协议官方团队开发，提供了与GitLab API交互的完整工具集。

项目基本信息

一、项目介绍

GitLab版本控制工具是MCP官方提供的GitLab集成服务器，让AI能够通过标准化协议与GitLab API交互。它支持项目管理、文件操作、Issue和合并请求管理等核心功能。

这个服务器提供了以下工具：

• 文件操作：create_or_update_file、push_files、get_file_contents
• 项目管理：search_repositories、create_repository、fork_repository
• 分支管理：create_branch
• Issue管理：create_issue
• 合并请求管理：create_merge_request

二、核心优势

官方维护

由MCP官方团队开发维护，与MCP协议同步更新，稳定可靠。

功能完整

覆盖GitLab核心操作：

• 文件创建、更新、推送
• 项目搜索、创建、分叉
• 分支创建
• Issue创建
• 合并请求创建

自动分支创建

在创建/更新文件或推送更改时，如果分支不存在会自动创建，简化工作流程。

批量操作

支持单文件和多文件操作，可以在单个提交中推送多个文件。

多部署方式

支持Docker和NPX两种运行方式。

三、适用场景

AI辅助GitLab管理

让AI帮你创建项目、管理文件、处理Issue和MR。

自动化CI/CD

AI可以自动创建分支、提交代码、创建合并请求。

项目管理自动化

AI可以根据需求自动创建Issue，分配给相关人员。

代码仓库初始化

AI可以自动创建项目并初始化README文件。

四、安装教程

系统要求

安装步骤

第一步：创建GitLab个人访问令牌

1. 登录GitLab
2. 进入"用户设置" -> "访问令牌"

3. 选择所需范围：

   • api：完整API访问权限
   • read_api：只读访问权限
   • read_repository和write_repository：仓库操作权限
4. 创建令牌并安全保存

第二步：配置MCP客户端

对于Claude Desktop：

找到配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

使用NPX（推荐）：

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "你的令牌",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

使用Docker：

{
  "mcpServers": {
    "gitlab": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "GITLAB_PERSONAL_ACCESS_TOKEN", "-e", "GITLAB_API_URL", "mcp/gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "你的令牌",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

对于自托管GitLab实例：
将GITLAB_API_URL改为你的实例API地址，例如https://gitlab.example.com/api/v4。

五、使用示例

配置完成后，你就可以在MCP客户端中使用自然语言来操作GitLab了。

示例1：创建项目

用户指令：“创建一个名为my-project的新项目，描述为‘测试项目’，设置为私有”

AI会调用create_repository工具：

{
  "name": "my-project",
  "description": "测试项目",
  "visibility": "private",
  "initialize_with_readme": true
}

示例2：创建或更新文件

用户指令：“在my-project项目的main分支上创建README.md文件”

AI会调用create_or_update_file工具：

{
  "project_id": "my-project",
  "file_path": "README.md",
  "content": "# My Project\n\nThis is a test project.",
  "commit_message": "Initial README",
  "branch": "main"
}

示例3：批量推送文件

用户指令：“一次性推送src目录下的所有文件”

AI会调用push_files工具：

{
  "project_id": "my-project",
  "branch": "main",
  "files": [
    {"file_path": "src/index.js", "content": "console.log('hello');"},
    {"file_path": "src/utils.js", "content": "export const add = (a,b) => a+b;"}
  ],
  "commit_message": "Add source files"
}

示例4：创建Issue

用户指令：“在my-project中创建一个标题为‘Bug：登录页面崩溃’的Issue”

AI会调用create_issue工具：

{
  "project_id": "my-project",
  "title": "Bug：登录页面崩溃",
  "description": "详细描述问题...",
  "labels": ["bug", "high-priority"]
}

示例5：创建合并请求

用户指令：“从feature分支向main分支创建一个合并请求，标题为‘添加用户认证功能’”

AI会调用create_merge_request工具：

{
  "project_id": "my-project",
  "title": "添加用户认证功能",
  "source_branch": "feature",
  "target_branch": "main",
  "description": "实现了JWT认证",
  "draft": false
}

示例6：搜索项目

用户指令：“搜索名称中包含‘api’的项目”

AI会调用search_repositories工具：

{
  "search": "api",
  "per_page": 10
}

示例7：分叉项目

用户指令：“将my-project分叉到我的命名空间”

AI会调用fork_repository工具：

{
  "project_id": "my-project",
  "namespace": "my-namespace"
}

示例8：创建分支

用户指令：“从main分支创建名为feature-login的新分支”

AI会调用create_branch工具：

{
  "project_id": "my-project",
  "branch": "feature-login",
  "ref": "main"
}

示例9：获取文件内容

用户指令：“获取README.md文件的内容”

AI会调用get_file_contents工具：

{
  "project_id": "my-project",
  "file_path": "README.md",
  "ref": "main"
}

六、常见问题

问题1：提示“401 Unauthorized”

解决方案：

• 确认GitLab个人访问令牌正确且未过期
• 检查令牌是否包含所需的权限范围

问题2：项目ID格式

解决方案：project_id可以是数字ID或URL编码的项目路径，如my-group%2Fmy-project。

问题3：自托管GitLab实例配置

解决方案：设置GITLAB_API_URL环境变量为你的实例API地址。

问题4：分支不存在时自动创建

解决方案：服务器支持自动创建分支，无需手动创建。

问题5：文件路径格式

解决方案：使用相对于项目根目录的路径，如src/main.py。

七、总结

GitLab版本控制工具是MCP官方提供的GitLab集成服务器，让AI能够通过标准化协议操作GitLab仓库。

这个项目的最大价值在于：

1. 官方维护：由MCP官方团队开发，稳定可靠
2. 功能完整：覆盖文件操作、项目管理、Issue、MR等核心功能
3. 自动分支创建：简化工作流程
4. 批量操作：支持多文件推送
5. 多部署方式：支持NPX和Docker

如果你是GitLab用户，并且希望用AI来辅助版本控制操作，GitLab版本控制工具是一个非常实用的选择。