GitLab项目管理服务器（TheRealChrisThomas） - MCP Server 功能介绍与安装配置

Name: GitLab项目管理服务器
Author: TheRealChrisThomas

使用说明

GitLab MCP服务器

用于GitLab API的MCP服务器，实现项目管理、文件操作等。分叉自https://github.com/modelcontextprotocol

安装

NPX（推荐）

npx @therealchristhomas/gitlab-mcp-server

全球安装

npm install -g @therealchristhomas/gitlab-mcp-server
gitlab-mcp

特性

自动创建分支：在创建/更新文件或推送更改时，如果分支不存在，则会自动创建分支
全面的错误处理：清除常见问题的错误消息
Git历史保存：操作维护正确的Git历史记录，无需强制推送
批量操作：支持单文件和多文件操作
项目工作流管理：标签和里程碑管理，以更好地组织项目
库管理：搜索、创建和分叉GitLab项目
文件操作：创建、更新和检索文件内容
分行管理：创建分支并管理存储库结构
问题管理：创建、列出、更新、搜索和评论问题
合并请求管理：列出、更新、合并和评论合并请求
标签管理：创建、更新和删除项目标签
里程碑：创建、更新和删除项目级里程碑
集团里程碑：创建、更新和删除跨越多个项目的组级里程碑

集团里程碑与项目里程碑

此服务器同时支持 项目里程碑 和 小组里程碑:

里程碑

仅限于一个项目
使用工具： list_milestones, create_milestone, update_milestone, delete_milestone
示例：跟踪功能 my-webapp 项目

集团里程碑

跨组内的多个项目
使用工具： list_group_milestones, create_group_milestone, update_group_milestone, delete_group_milestone
支持高级过滤 include_ancestors, include_descendants
示例：跨平台跟踪发布 my-webapp, my-api，以及 my-admin

集团里程碑示例

列出集团里程碑

{
  "group_id": "my-organization",
  "state": "active",
  "include_descendants": true
}

创建组里程碑

{
  "group_id": "my-organization",
  "title": "Q1 2025 Release",
  "description": "Major feature release including new tools and performance improvements",
  "due_date": "2025-03-31",
  "start_date": "2025-01-01"
}

高级组里程碑搜索

{
  "group_id": "my-organization/core",
  "search": "release",
  "include_ancestors": true,
  "updated_after": "2024-01-01T00:00:00Z"
}

基于 GitLab集团里程碑API，组里程碑是协调组织中多个项目的发布和功能的理想选择。

实用工作流程：查找组和创建里程碑

以下是处理团队里程碑的典型工作流程：

1.搜索组

首先，找到你想合作的团队：

{
  "search": "my-organization",
  "owned": true
}

2.列出现有集团里程碑

检查哪些里程碑已经存在：

{
  "group_id": "my-organization",
  "state": "active"
}

3.创建组里程碑

创建一个跨越多个项目的里程碑：

{
  "group_id": "my-organization",
  "title": "Q1 2025 Release",
  "description": "Cross-project release including webapp, API, and admin features",
  "due_date": "2025-03-31"
}

此工作流对于同一组下有多个相关项目的大型组织特别有用。

工具

文件操作

create_or_update_file
- 在项目中创建或更新单个文件
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - file_path （string）：创建/更新文件的路径
  - content （string）：文件内容
  - commit_message （string）：提交消息
  - branch （string）：创建/更新文件的分支
  - previous_path （可选字符串）：要移动/重命名的文件的路径
- 返回：文件内容和提交详细信息
push_files
- 在一次提交中推送多个文件
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - branch （string）：要推送的分支
  - files （array）：要推送的文件，每个文件都有 file_path 和 content
  - commit_message （string）：提交消息
- 返回：更新了分支引用
get_file_contents
- 获取文件或目录的内容
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - file_path （string）：文件/目录的路径
  - ref （可选字符串）：从Branch/tag/commit获取内容
- 返回：文件/目录内容

库管理

search_repositories
- 搜索GitLab项目
- 输入：
  - search （string）：搜索查询
  - page （可选编号）：分页页码
  - per_page （可选数字）：每页结果（默认值20）
- 返回：项目搜索结果
create_repository
- 创建一个新的GitLab项目
- 输入：
  - name （string）：项目名称
  - description （可选字符串）：项目描述
  - visibility （可选字符串）：“private”、“internal”或“public”
  - initialize_with_readme （可选布尔值）：使用README进行初始化
- 返回：已创建项目详细信息
fork_repository
- 分叉项目
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - namespace （可选字符串）：要分叉到的命名空间
- 返回：分叉项目详细信息
create_branch
- 创建新分支
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - branch （string）：新分支的名称
  - ref （可选字符串）：源分支/新分支的提交
- 返回：已创建分支引用

组操作

search_groups
- 搜索GitLab群组
- 输入：
  - search （string）：组搜索查询
  - page （可选编号）：分页页码
  - per_page （可选数字）：每页结果（默认值20）
  - owned （可选布尔值）：按当前用户拥有的组进行限制
  - min_access_level （可选数字）：最低访问级别（10=访客，20=报告者，30=开发人员，40=维护人员，50=所有者）
- 返回：分组搜索结果

问题管理

create_issue
- 创建新问题
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - title （string）：发行标题
  - description （可选字符串）：问题描述
  - assignee_ids （可选编号[]）：要分配的用户ID
  - labels （可选字符串[]）：要添加的标签
  - milestone_id （可选编号）：里程碑ID
- 退货：已创建问题详细信息
list_issues
- 列出GitLab项目中的所有问题
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - state （可选字符串）：“打开”、“关闭”或“全部”
  - labels （可选字符串）：以逗号分隔的标签名称列表
  - milestone （可选字符串）：里程碑标题
  - assignee_id （可选编号）：受让人的用户ID
  - author_id （可选编号）：作者的用户名
  - search （可选字符串）：根据标题和描述进行搜索
  - created_after （可选字符串）：返回日期后创建的问题（ISO 8601）
  - created_before （可选字符串）：返回日期之前创建的问题（ISO 8601）
  - updated_after （可选字符串）：返回日期后更新的问题（ISO 8601）
  - updated_before （可选字符串）：返回日期之前更新的问题（ISO 8601）
  - sort （可选字符串）：按各种标准对问题进行排序
  - order_by （可选字符串）：“asc”或“desc”
  - page （可选编号）：分页页码
  - per_page （可选数字）：每页结果（默认值20）
  - with_labels_details （可选布尔值）：如果为true，则返回每个标签的更多详细信息。默认值为false。
- 返回：问题对象数组
update_issue
- 更新GitLab项目中的现有问题
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - issue_iid （编号）：发布内部ID
  - title （可选字符串）：新问题标题
  - description （可选字符串）：新问题描述
  - state_event （可选字符串）：“关闭”或“重新打开”
  - labels （可选字符串[]）：标签名称数组
  - assignee_ids （可选数字[]）：要分配的用户ID数组
  - milestone_id （可选编号）：要分配的里程碑ID
- 退货：更新的问题详细信息
search_issues
- 在GitLab项目中搜索问题
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - search （string）：标题和描述的搜索词
  - state （可选字符串）：“打开”、“关闭”或“全部”
  - labels （可选字符串）：以逗号分隔的标签名称列表
  - page （可选编号）：分页页码
  - per_page （可选数字）：每页结果（默认值20）
- 返回：匹配问题对象的数组
add_issue_comment
- 在GitLab项目中为问题添加评论
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - issue_iid （编号）：发布内部ID
  - body （string）：评论的内容
- 返回：已创建评论详细信息

合并请求管理

create_merge_request

创建新的合并请求
输入：
- project_id （string）：项目ID或URL编码路径
- title （字符串）：MR标题
- description （可选字符串）：MR描述
- source_branch （string）：包含更改的分支
- target_branch （string）：要合并的分支
- draft （可选布尔值）：创建为草稿MR
- allow_collaboration （可选布尔值）：允许来自上游成员的提交
返回：已创建合并请求详细信息

list_merge_requests
- 列出GitLab项目中的所有合并请求
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - state （可选字符串）：“打开”、“关闭”、“锁定”、“合并”或“全部”
  - target_branch （可选字符串）：按目标分支筛选
  - source_branch （可选字符串）：按源分支筛选
  - labels （可选字符串）：以逗号分隔的标签名称列表
  - milestone （可选字符串）：里程碑标题
  - assignee_id （可选编号）：受让人的用户ID
  - author_id （可选编号）：作者的用户名
  - search （可选字符串）：根据标题和描述进行搜索
  - created_after （可选字符串）：返回日期后创建的MR（ISO 8601）
  - created_before （可选字符串）：返回日期之前创建的MR（ISO 8601）
  - updated_after （可选字符串）：返回日期后更新的MR（ISO 8601）
  - updated_before （可选字符串）：返回日期之前更新的MR（ISO 8601）
  - sort （可选字符串）：对合并请求进行排序
  - order_by （可选字符串）：“asc”或“desc”
  - page （可选编号）：分页页码
  - per_page （可选数字）：每页结果（默认值20）
- 返回：合并请求对象数组
update_merge_request
- 更新GitLab项目中的现有合并请求
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - merge_request_iid （number）：合并请求内部ID
  - title （可选字符串）：新合并请求标题
  - description （可选字符串）：新合并请求描述
  - state_event （可选字符串）：“关闭”或“重新打开”
  - target_branch （可选字符串）：新建目标分支
  - labels （可选字符串[]）：标签名称数组
  - assignee_ids （可选数字[]）：要分配的用户ID数组
  - milestone_id （可选编号）：要分配的里程碑ID
  - remove_source_branch （可选布尔值）：合并时删除源分支
- 返回：更新了合并请求详细信息
merge_merge_request
- 在GitLab项目中合并合并请求
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - merge_request_iid （number）：合并请求内部ID
  - merge_commit_message （可选字符串）：自定义合并提交消息
  - should_remove_source_branch （可选布尔值）：合并后删除源分支
  - merge_when_pipeline_succeeds （可选布尔值）：管道成功时合并
  - sha （可选字符串）：必须与源分支HEAD匹配的SHA
- 返回：合并的合并请求详细信息
add_merge_request_comment
- 在GitLab项目中为合并请求添加注释
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - merge_request_iid （number）：合并请求内部ID
  - body （string）：评论的内容
- 返回：已创建评论详细信息

标签管理

list_labels
- 列出项目中的所有标签
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - page （可选编号）：分页页码
  - per_page （可选数字）：每页结果（默认值20）
- 返回：标签对象数组
create_label
- 创建新标签
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - name （string）：标签名称
  - color （字符串）：标签颜色（十六进制代码）
  - description （可选字符串）：标签描述
  - priority （可选编号）：标签优先级
- 返回：已创建标签详细信息
update_label
- 更新现有标签
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - name （string）：当前标签名称
  - new_name （可选字符串）：新标签名称
  - color （可选字符串）：新标签颜色
  - description （可选字符串）：新标签描述
  - priority （可选编号）：新标签优先级
- 返回：更新标签详细信息
delete_label
- 删除标签
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - name （string）：要删除的标签名称
- 返回：成功确认

里程碑管理

list_milestones
- 列出项目中的所有里程碑
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - state （可选字符串）：“活动”或“关闭”
  - page （可选编号）：分页页码
  - per_page （可选数字）：每页结果（默认值20）
- 返回值：里程碑对象数组
create_milestone
- 创建新的里程碑
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - title （string）：里程碑标题
  - description （可选字符串）：里程碑描述
  - due_date （可选字符串）：到期日期（YYYY-MM-DD）
  - start_date （可选字符串）：开始日期（YYYY-MM-DD）
- 返回：已创建里程碑详细信息
update_milestone
- 更新现有里程碑
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - milestone_id （编号）：里程碑ID
  - title （可选字符串）：新标题
  - description （可选字符串）：新描述
  - due_date （可选字符串）：新的截止日期
  - start_date （可选字符串）：新的开始日期
  - state_event （可选字符串）：“关闭”或“激活”
- 返回：更新的里程碑详细信息
delete_milestone
- 删除里程碑
- 输入：
  - project_id （string）：项目ID或URL编码路径
  - milestone_id （编号）：要删除的里程碑ID
- 返回：成功确认
list_group_milestones
- 列出GitLab组中的所有里程碑
- 输入：
  - group_id （string）：组ID或URL编码路径
  - state （可选字符串）：“活动”或“关闭”
  - title （可选字符串）：按里程碑标题筛选（区分大小写）
  - search （可选字符串）：在标题或描述中搜索
  - search_title （可选字符串）：仅在标题中搜索
  - include_ancestors （可选布尔值）：包括父组里程碑
  - include_descendants （可选布尔值）：包括子组里程碑
  - updated_before （可选字符串）：按更新日期筛选（ISO 8601）
  - updated_after （可选字符串）：按更新日期筛选（ISO 8601）
  - containing_date （可选字符串）：包含给定日期的里程碑
  - start_date （可选字符串）：过滤due_date>=start_date的位置
  - end_date （可选字符串）：筛选start_date<=end_date的位置
  - page （可选编号）：分页页码
  - per_page （可选数字）：每页结果（默认值20）
- 返回值：组里程碑对象数组
create_group_milestone
- 在GitLab组中创建新的里程碑
- 输入：
  - group_id （string）：组ID或URL编码路径
  - title （string）：里程碑标题
  - description （可选字符串）：里程碑描述
  - due_date （可选字符串）：到期日期（YYYY-MM-DD）
  - start_date （可选字符串）：开始日期（YYYY-MM-DD）
- 返回：已创建组里程碑详细信息
update_group_milestone
- 更新GitLab组中的现有里程碑
- 输入：
  - group_id （string）：组ID或URL编码路径
  - milestone_id （编号）：里程碑ID
  - title （可选字符串）：新标题
  - description （可选字符串）：新描述
  - due_date （可选字符串）：新的截止日期
  - start_date （可选字符串）：新的开始日期
  - state_event （可选字符串）：“关闭”或“激活”
- 返回：更新了组里程碑详细信息
delete_group_milestone
- 从GitLab组中删除里程碑
- 输入：
  - group_id （string）：组ID或URL编码路径
  - milestone_id （编号）：要删除的里程碑ID
- 返回：成功确认

设置

个人访问令牌

创建GitLab个人访问令牌具有适当的权限：

转到用户设置>访问GitLab中的令牌
选择所需的范围：
- api 用于API的完全访问
- read_api 用于只读访问
- read_repository 和 write_repository 用于存储库操作
创建令牌并安全保存

使用Claude Desktop

将以下内容添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@therealchristhomas/gitlab-mcp-server"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

使用光标/VCode/Wisurf

将以下内容添加到MCP配置中：

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@therealchristhomas/gitlab-mcp-server"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

备注：替换 <YOUR_TOKEN> 使用您实际的GitLab个人访问令牌。此外，如果您不使用Gitlab.com，请替换为您的Gitlab API URL

环境变量

GITLAB_PERSONAL_ACCESS_TOKEN：您的GitLab个人访问令牌（必填）
GITLAB_API_URL：GitLab API的基本URL（可选，默认为 https://gitlab.com/api/v4)

对于自托管的GitLab实例，请更新 GITLAB_API_URL 指向您的实例：

"GITLAB_API_URL": "https://your-gitlab-instance.com/api/v4"

发展

构建

npm run build

开发模式

npm run dev

观看模式

npm run watch

许可证

此MCP服务器根据MIT许可证获得许可。这意味着您可以根据MIT许可证的条款和条件自由使用、修改和分发软件。有关更多详细信息，请参阅项目存储库中的LICENSE文件。