mcpField
G
GitLab MCP Server

GitLab MCP Server

本地服务
github.com/TheRealChrisThomas版本控制171 周前更新
代码仓库

关于 GitLab MCP Server

GitLab MCP Server 将 GitLab 项目和群组操作提供给 MCP 客户端。它涵盖仓库、文件、议题、合并请求、标签及项目和群组级里程碑，并支持批量文件变更和自动创建分支。

主要功能

  1. 01搜索、创建和派生仓库
  2. 02创建、读取文件及批量推送
  3. 03管理分支、议题和合并请求
  4. 04管理标签与项目里程碑
  5. 05管理跨项目的群组里程碑

适用场景

  1. 01创建或更新单个及多个项目文件
  2. 02通过 MCP 客户端跟进议题和合并请求
  3. 03协调 GitLab 群组内多个项目的里程碑

MCP 相关

该服务将 GitLab API 操作接入 MCP 客户端，提供项目、仓库、议题、合并请求、标签和里程碑工具。

#open-source#gitlab#typescript#mcp

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "gitlab-mcp-server-therealchristhomas": {
      "command": "npx",
      "args": [
        "-y",
        "@therealchristhomas/gitlab-mcp-server"
      ]
    }
  }
}
启动命令npx -y @therealchristhomas/gitlab-mcp-server

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
npm@therealchristhomas/gitlab-mcp-server

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

MCP 标志

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"
}

对于同一群组下有多个相关项目的大型组织，此工作流尤其有用。

工具

文件操作

  1. create_or_update_file

    • 在项目中创建或更新单个文件
    • 输入：
      • project_id（string）：项目 ID 或经过 URL 编码的路径
      • file_path（string）：创建或更新文件的位置
      • content（string）：文件内容
      • commit_message（string）：提交消息
      • branch（string）：用于创建或更新文件的分支
      • previous_path（可选 string）：要移动或重命名的文件路径
    • 返回：文件内容和提交详情

  2. push_files

    • 在单次提交中推送多个文件
    • 输入：
      • project_id（string）：项目 ID 或经过 URL 编码的路径
      • branch（string）：要推送到的分支
      • files（array）：要推送的文件，每个文件包含 file_path 和 content
      • commit_message（string）：提交消息
    • 返回：更新后的分支引用

  3. get_file_contents

    • 获取文件或目录的内容
    • 输入：
      • project_id（string）：项目 ID 或经过 URL 编码的路径
      • file_path（string）：文件或目录的路径
      • ref（可选 string）：要从中获取内容的分支、标签或提交
    • 返回：文件或目录内容
仓库管理

  1. search_repositories

    • 搜索 GitLab 项目
    • 输入：
      • search（string）：搜索查询
      • page（可选 number）：分页页码
      • per_page（可选 number）：每页结果数（默认 20）
    • 返回：项目搜索结果

  2. create_repository

    • 创建新的 GitLab 项目
    • 输入：
      • name（string）：项目名称
      • description（可选 string）：项目描述
      • visibility（可选 string）：'private'、'internal' 或 'public'
      • initialize_with_readme（可选 boolean）：使用 README 初始化
    • 返回：已创建项目的详情

  3. fork_repository

    • 派生项目
    • 输入：
      • project_id（string）：项目 ID 或经过 URL 编码的路径
      • namespace（可选 string）：要派生到的命名空间
    • 返回：已派生项目的详情

  4. create_branch

    • 创建新分支
    • 输入：
      • project_id（string）：项目 ID 或经过 URL 编码的路径
      • branch（string）：新分支的名称
      • ref（可选 string）：新分支的源分支或提交
    • 返回：已创建分支的引用
群组操作

  1. search_groups

    • 搜索 GitLab 群组
    • 输入：
      • search（string）：群组搜索查询
      • page（可选 number）：分页页码
      • per_page（可选 number）：每页结果数（默认 20）
      • owned（可选 boolean）：仅限当前用户拥有的群组
      • min_access_level（可选 number）：最低访问级别（10=访客，20=报告者，30=开发者，40=维护者，50=所有者）
    • 返回：群组搜索结果
问题管理

  1. create_issue

    • 创建新问题
    • 输入：
      • project_id (string)：项目 ID 或 URL 编码路径
      • title (string)：问题标题
      • description (optional string)：问题描述
      • assignee_ids (optional number[])：要分配的用户 ID
      • labels (optional string[])：要添加的标签
      • milestone_id (optional number)：里程碑 ID
    • 返回：已创建的问题详情

  2. list_issues

    • 列出 GitLab 项目中的所有问题
    • 输入：
      • project_id (string)：项目 ID 或 URL 编码路径
      • state (optional string)：'opened'、'closed' 或 'all'
      • labels (optional string)：以逗号分隔的标签名称列表
      • milestone (optional string)：里程碑标题
      • assignee_id (optional number)：被分配者的用户 ID
      • author_id (optional number)：作者的用户 ID
      • search (optional string)：搜索标题和描述
      • created_after (optional string)：返回在此日期之后创建的问题（ISO 8601）
      • created_before (optional string)：返回在此日期之前创建的问题（ISO 8601）
      • updated_after (optional string)：返回在此日期之后更新的问题（ISO 8601）
      • updated_before (optional string)：返回在此日期之前更新的问题（ISO 8601）
      • sort (optional string)：按各种条件对问题排序
      • order_by (optional string)：'asc' 或 'desc'
      • page (optional number)：分页页码
      • per_page (optional number)：每页结果数（默认值为 20）
      • with_labels_details (optional boolean)：如果为 true，则返回每个标签的更多详情。默认值为 false。
    • 返回：问题对象数组

  3. update_issue

    • 更新 GitLab 项目中的现有问题
    • 输入：
      • project_id (string)：项目 ID 或 URL 编码路径
      • issue_iid (number)：问题内部 ID
      • title (optional string)：新问题标题
      • description (optional string)：新问题描述
      • state_event (optional string)：'close' 或 'reopen'
      • labels (optional string[])：标签名称数组
      • assignee_ids (optional number[])：要分配的用户 ID 数组
      • milestone_id (optional number)：要分配的里程碑 ID
    • 返回：已更新的问题详情

  4. search_issues

    • 搜索 GitLab 项目中的问题
    • 输入：
      • project_id (string)：项目 ID 或 URL 编码路径
      • search (string)：用于搜索标题和描述的词语
      • state (optional string)：'opened'、'closed' 或 'all'
      • labels (optional string)：以逗号分隔的标签名称列表
      • page (optional number)：分页页码
      • per_page (optional number)：每页结果数（默认值为 20）
    • 返回：匹配的问题对象数组

  5. add_issue_comment

    • 向 GitLab 项目中的问题添加评论
    • 输入：
      • project_id (string)：项目 ID 或 URL 编码路径
      • issue_iid (number)：问题内部 ID
      • body (string)：评论内容
    • 返回：已创建的评论详情
合并请求管理
  1. create_merge_request
  • 创建新的合并请求
  • 输入：
    • project_id（string）：项目 ID 或经过 URL 编码的路径
    • title（string）：MR 标题
    • description（可选 string）：MR 描述
    • source_branch（string）：包含更改的分支
    • target_branch（string）：要合并到的分支
    • draft（可选 boolean）：创建为草稿 MR
    • allow_collaboration（可选 boolean）：允许上游成员提交更改
  • 返回：已创建的合并请求详情

  1. list_merge_requests

    • 列出 GitLab 项目中的所有合并请求
    • 输入：
      • project_id（string）：项目 ID 或经过 URL 编码的路径
      • state（可选 string）：'opened'、'closed'、'locked'、'merged' 或 'all'
      • target_branch（可选 string）：按目标分支筛选
      • source_branch（可选 string）：按源分支筛选
      • labels（可选 string）：以逗号分隔的标签名称列表
      • milestone（可选 string）：里程碑标题
      • assignee_id（可选 number）：受指派者的用户 ID
      • author_id（可选 number）：作者的用户 ID
      • search（可选 string）：搜索标题和描述
      • created_after（可选 string）：返回此日期之后创建的 MR（ISO 8601）
      • created_before（可选 string）：返回此日期之前创建的 MR（ISO 8601）
      • updated_after（可选 string）：返回此日期之后更新的 MR（ISO 8601）
      • updated_before（可选 string）：返回此日期之前更新的 MR（ISO 8601）
      • sort（可选 string）：排序合并请求
      • order_by（可选 string）：'asc' 或 'desc'
      • page（可选 number）：分页页码
      • per_page（可选 number）：每页结果数（默认 20）
    • 返回：合并请求对象数组

  2. update_merge_request

    • 更新 GitLab 项目中现有的合并请求
    • 输入：
      • project_id（string）：项目 ID 或经过 URL 编码的路径
      • merge_request_iid（number）：合并请求内部 ID
      • title（可选 string）：新的合并请求标题
      • description（可选 string）：新的合并请求描述
      • state_event（可选 string）：'close' 或 'reopen'
      • target_branch（可选 string）：新的目标分支
      • labels（可选 string[]）：标签名称数组
      • assignee_ids（可选 number[]）：要指派的用户 ID 数组
      • milestone_id（可选 number）：要指派的里程碑 ID
      • remove_source_branch（可选 boolean）：合并时删除源分支
    • 返回：已更新的合并请求详情

  3. merge_merge_request

    • 合并 GitLab 项目中的合并请求
    • 输入：
      • project_id（string）：项目 ID 或经过 URL 编码的路径
      • merge_request_iid（number）：合并请求内部 ID
      • merge_commit_message（可选 string）：自定义合并提交消息
      • should_remove_source_branch（可选 boolean）：合并后删除源分支
      • merge_when_pipeline_succeeds（可选 boolean）：流水线成功后合并
      • sha（可选 string）：必须与源分支 HEAD 匹配的 SHA
    • 返回：已合并的合并请求详情

  4. add_merge_request_comment

    • 在 GitLab 项目的合并请求中添加评论
    • 输入：
      • project_id（string）：项目 ID 或经过 URL 编码的路径
      • merge_request_iid（number）：合并请求内部 ID
      • body（string）：评论内容
    • 返回：已创建的评论详情
标签管理

  1. list_labels

    • 列出项目中的所有标签
    • 输入：
      • project_id（string）：项目 ID 或 URL 编码的路径
      • page（可选 number）：分页页码
      • per_page（可选 number）：每页结果数（默认 20）
    • 返回：标签对象数组

  2. create_label

    • 创建新标签
    • 输入：
      • project_id（string）：项目 ID 或 URL 编码的路径
      • name（string）：标签名称
      • color（string）：标签颜色（十六进制代码）
      • description（可选 string）：标签描述
      • priority（可选 number）：标签优先级
    • 返回：创建的标签详情

  3. update_label

    • 更新现有标签
    • 输入：
      • project_id（string）：项目 ID 或 URL 编码的路径
      • name（string）：当前标签名称
      • new_name（可选 string）：新标签名称
      • color（可选 string）：新标签颜色
      • description（可选 string）：新标签描述
      • priority（可选 number）：新标签优先级
    • 返回：更新后的标签详情

  4. delete_label

    • 删除标签
    • 输入：
      • project_id（string）：项目 ID 或 URL 编码的路径
      • name（string）：要删除的标签名称
    • 返回：成功确认
里程碑管理

  1. list_milestones

    • 列出项目中的所有里程碑
    • 输入：
      • project_id（string）：项目 ID 或 URL 编码路径
      • state（可选 string）：'active' 或 'closed'
      • page（可选 number）：分页页码
      • per_page（可选 number）：每页结果数（默认值为 20）
    • 返回：里程碑对象数组

  2. create_milestone

    • 创建新里程碑
    • 输入：
      • project_id（string）：项目 ID 或 URL 编码路径
      • title（string）：里程碑标题
      • description（可选 string）：里程碑描述
      • due_date（可选 string）：截止日期（YYYY-MM-DD）
      • start_date（可选 string）：开始日期（YYYY-MM-DD）
    • 返回：已创建的里程碑详情

  3. update_milestone

    • 更新现有里程碑
    • 输入：
      • project_id（string）：项目 ID 或 URL 编码路径
      • milestone_id（number）：里程碑 ID
      • title（可选 string）：新标题
      • description（可选 string）：新描述
      • due_date（可选 string）：新截止日期
      • start_date（可选 string）：新开始日期
      • state_event（可选 string）：'close' 或 'activate'
    • 返回：已更新的里程碑详情

  4. delete_milestone

    • 删除里程碑
    • 输入：
      • project_id（string）：项目 ID 或 URL 编码路径
      • milestone_id（number）：要删除的里程碑 ID
    • 返回：成功确认

  5. list_group_milestones

    • 列出 GitLab 群组中的所有里程碑
    • 输入：
      • group_id（string）：群组 ID 或 URL 编码路径
      • state（可选 string）：'active' 或 'closed'
      • title（可选 string）：按里程碑标题筛选（区分大小写）
      • search（可选 string）：在标题或描述中搜索
      • search_title（可选 string）：仅在标题中搜索
      • include_ancestors（可选 boolean）：包含父群组的里程碑
      • include_descendants（可选 boolean）：包含子群组的里程碑
      • updated_before（可选 string）：按更新时间筛选（ISO 8601）
      • updated_after（可选 string）：按更新时间筛选（ISO 8601）
      • containing_date（可选 string）：包含指定日期的里程碑
      • start_date（可选 string）：筛选 due_date >= start_date 的结果
      • end_date（可选 string）：筛选 start_date <= end_date 的结果
      • page（可选 number）：分页页码
      • per_page（可选 number）：每页结果数（默认值为 20）
    • 返回：群组里程碑对象数组

  6. create_group_milestone

    • 在 GitLab 群组中创建新里程碑
    • 输入：
      • group_id（string）：群组 ID 或 URL 编码路径
      • title（string）：里程碑标题
      • description（可选 string）：里程碑描述
      • due_date（可选 string）：截止日期（YYYY-MM-DD）
      • start_date（可选 string）：开始日期（YYYY-MM-DD）
    • 返回：已创建的群组里程碑详情

  7. update_group_milestone

    • 更新 GitLab 群组中的现有里程碑
    • 输入：
      • group_id（string）：群组 ID 或 URL 编码路径
      • milestone_id（number）：里程碑 ID
      • title（可选 string）：新标题
      • description（可选 string）：新描述
      • due_date（可选 string）：新截止日期
      • start_date（可选 string）：新开始日期
      • state_event（可选 string）：'close' 或 'activate'
    • 返回：已更新的群组里程碑详情

  8. delete_group_milestone

    • 从 GitLab 群组中删除里程碑
    • 输入：
      • group_id（string）：群组 ID 或 URL 编码路径
      • milestone_id（number）：要删除的里程碑 ID
    • 返回：成功确认

设置

Personal Access Token

创建 GitLab Personal Access Token，并授予适当的权限：

  • 在 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"
      }
    }
  }
}
在 Cursor/VSCode/Winsurf 中使用

将以下内容添加到你的 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 Personal Access Token。如果你未使用 gitlab.com，也请将其替换为你的 Gitlab API URL。

环境变量

  • GITLAB_PERSONAL_ACCESS_TOKEN：你的 GitLab personal access token（必需）
  • 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 License 许可。这意味着你可以自由使用、修改和分发该软件，但须遵守 MIT License 的条款和条件。更多详情请参阅项目仓库中的 LICENSE 文件。

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。