hll_gitlab_mcp_server

v2.0.25

Published

a month ago

MCP server for using the GitLab API (Huolala Internal Fork)

0High
0Medium
0Low

wenbochang888

GitLab MCP Server

项目来源：本项目 fork 自 zereight/gitlab-mcp v2.0.24，为保证企业数据安全，托管在货拉拉内部 GitLab。感谢原作者 @zereight 的开源贡献！

让 AI 助手能够自动操作 GitLab 的工具 —— 通过自然语言完成代码提交、创建 MR、管理 Issue 等操作。

📦 快速开始

最简配置 - 使用个人访问令牌（推荐）：

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@huolala/[email protected]"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "你的_gitlab_令牌",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "CURSOR_OPTIMIZED_MODE": "true"
      }
    }
  }
}

⚠️ 重要: 强烈建议设置 CURSOR_OPTIMIZED_MODE=true，因为 Cursor 对 MCP 工具数量有限制。启用此模式后，只暴露代码管理和 MR 核心功能（25 个工具），确保最佳性能。

🔐 认证方式

个人访问令牌（推荐）

获取步骤：

登录 GitLab → 点击头像 → Settings（设置）
左侧菜单 → Access Tokens（访问令牌）
创建新令牌，勾选 api 权限
复制生成的令牌

配置示例：

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@huolala/[email protected]"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "CURSOR_OPTIMIZED_MODE": "true"
      }
    }
  }
}

⚠️ 版本管理

重要提示：出于安全性和稳定性考虑，所有安装配置均使用固定版本号：

"args": ["-y", "@huolala/[email protected]"]

为什么固定版本？

✅ 避免自动安装未经测试的新版本
✅ 确保团队环境一致性
✅ 便于问题排查和回滚
✅ 符合企业安全规范

升级指引：需要升级时，请先在测试环境验证新版本，再统一更新版本号。

🎯 Cursor 优化模式

为什么需要优化模式？

Cursor 对 MCP 工具数量有限制，本项目完整模式包含 98 个工具。为确保稳定运行，我们提供了Cursor 优化模式：

✅ 精选 25 个核心工具：代码管理（16 个）+ MR 基础操作（5 个）+ MR 代码差异（4 个）
✅ 覆盖日常开发 80% 场景：文件操作、分支管理、MR 创建与审查
✅ 轻量高效：工具数量少，加载快，响应快
✅ 所有代码保留：其他功能代码依然存在，只是不在 MCP 中暴露

如何启用？

在配置中添加环境变量 CURSOR_OPTIMIZED_MODE=true 即可（见下方快速开始）。

⚙️ 配置说明

必需配置

| 环境变量 | 说明 | 示例 | |---------|------|------| | GITLAB_PERSONAL_ACCESS_TOKEN | GitLab 个人访问令牌（使用 OAuth 时不需要） | glpat-xxxxx | | GITLAB_API_URL | GitLab API 地址 | https://gitlab.com/api/v4 |

常用配置

| 环境变量 | 说明 | 默认值 | |---------|------|--------| | CURSOR_OPTIMIZED_MODE | 🔥 Cursor 优化模式（推荐）：只暴露核心 25 个工具（代码管理 + MR 基础），避免工具过多 | false | | GITLAB_PROJECT_ID | 默认项目 ID（可在请求中覆盖） | 无 | | GITLAB_READ_ONLY_MODE | 只读模式（只暴露读取操作） | false | | USE_GITLAB_WIKI | 启用 Wiki 相关工具（非 Cursor 优化模式时有效） | false | | USE_MILESTONE | 启用里程碑工具（非 Cursor 优化模式时有效） | false | | USE_PIPELINE | 启用 CI/CD 流水线工具（非 Cursor 优化模式时有效） | false | | GITLAB_ALLOWED_PROJECT_IDS | 允许访问的项目 ID 列表（逗号分隔） | 无 | | GITLAB_DENIED_TOOLS_REGEX | 排除工具的正则表达式 | 无 |

项目权限示例：

单个项目：GITLAB_ALLOWED_PROJECT_IDS=123 - 仅能访问项目 123
多个项目：GITLAB_ALLOWED_PROJECT_IDS=123,456,789 - 限制访问这 3 个项目

📦 完整功能模式

1️⃣ 代码管理（16 个）✅ Cursor 模式包含

| 工具名称 | 功能说明 | |---------|---------| | 文件操作 | | | create_or_update_file | 创建或更新单个文件 | | get_file_contents | 获取文件或目录内容 | | push_files | 批量提交多个文件 | | 分支管理 | | | create_branch | 创建新分支 | | get_branch_diffs | 获取两个分支/提交之间的差异 | | 提交管理 | | | list_commits | 列出仓库提交记录（支持筛选） | | get_commit | 获取指定提交详情 | | get_commit_diff | 获取提交的代码变更 | | 仓库操作 | | | search_repositories | 搜索 GitLab 项目 | | create_repository | 创建新项目 | | fork_repository | Fork 项目到个人账户 | | get_repository_tree | 获取仓库文件树结构 | | get_project | 获取项目详情 | | list_projects | 列出可访问的项目 | | list_project_members | 列出项目成员 | | list_group_projects | 列出群组下的项目 |

2️⃣ 合并请求（30 个）

| 工具名称 | 功能说明 | Cursor 模式 | |---------|---------|------------| | MR 基础操作 | | | | create_merge_request | 创建合并请求 | ✅ 包含 | | get_merge_request | 获取 MR 详情 | ✅ 包含 | | update_merge_request | 更新 MR | ✅ 包含 | | merge_merge_request | 合并 MR | ✅ 包含 | | list_merge_requests | 列出合并请求（支持全局或项目级） | ✅ 包含 | | MR 代码差异 | | | | get_merge_request_diffs | 获取 MR 的代码变更 | ✅ 包含 | | list_merge_request_diffs | 分页列出 MR 差异 | ✅ 包含 | | list_merge_request_versions | 列出 MR 的所有版本 | ✅ 包含 | | get_merge_request_version | 获取 MR 的特定版本 | ✅ 包含 | | MR 讨论与评论 | | | | mr_discussions | 列出 MR 讨论主题 | ⚠️ 完整模式 | | create_merge_request_thread | 创建新讨论主题 | ⚠️ 完整模式 | | resolve_merge_request_thread | 解决讨论主题 | ⚠️ 完整模式 | | create_merge_request_note | 添加 MR 评论 | ⚠️ 完整模式 | | get_merge_request_note | 获取特定 MR 评论 | ⚠️ 完整模式 | | get_merge_request_notes | 列出 MR 的所有评论 | ⚠️ 完整模式 | | update_merge_request_note | 修改 MR 评论 | ⚠️ 完整模式 | | delete_merge_request_note | 删除 MR 评论 | ⚠️ 完整模式 | | create_merge_request_discussion_note | 添加讨论回复 | ⚠️ 完整模式 | | update_merge_request_discussion_note | 更新讨论回复 | ⚠️ 完整模式 | | delete_merge_request_discussion_note | 删除讨论回复 | ⚠️ 完整模式 | | MR 草稿评论 | | | | get_draft_note | 获取单个草稿 | ⚠️ 完整模式 | | list_draft_notes | 列出所有草稿 | ⚠️ 完整模式 | | create_draft_note | 创建草稿评论 | ⚠️ 完整模式 | | update_draft_note | 更新草稿 | ⚠️ 完整模式 | | delete_draft_note | 删除草稿 | ⚠️ 完整模式 | | publish_draft_note | 发布单个草稿 | ⚠️ 完整模式 | | bulk_publish_draft_notes | 批量发布所有草稿 | ⚠️ 完整模式 | | MR 审批 | | | | approve_merge_request | 审批 MR | ⚠️ 完整模式 | | unapprove_merge_request | 取消审批 | ⚠️ 完整模式 | | get_merge_request_approval_state | 获取审批状态 | ⚠️ 完整模式 |

3️⃣ 问题管理（13 个）⚠️ 完整模式

| 工具名称 | 功能说明 | |---------|---------| | Issue 基础操作 | | | create_issue | 创建 Issue | | get_issue | 获取 Issue 详情 | | update_issue | 更新 Issue | | delete_issue | 删除 Issue | | list_issues | 列出 Issue（默认当前用户创建的） | | my_issues | 列出分配给我的 Issue | | Issue 讨论 | | | list_issue_discussions | 列出 Issue 讨论 | | create_issue_note | 添加 Issue 评论 | | update_issue_note | 修改 Issue 评论 | | Issue 关联 | | | list_issue_links | 列出 Issue 关联关系 | | get_issue_link | 获取特定关联 | | create_issue_link | 创建 Issue 之间的关联 | | delete_issue_link | 删除 Issue 关联 |

4️⃣ CI/CD 流水线（12 个）⚠️ 完整模式

| 工具名称 | 功能说明 | |---------|---------| | Pipeline 操作 | | | list_pipelines | 列出流水线（支持筛选） | | get_pipeline | 获取流水线详情 | | create_pipeline | 创建新流水线 | | retry_pipeline | 重试失败的流水线 | | cancel_pipeline | 取消运行中的流水线 | | Job 操作 | | | list_pipeline_jobs | 列出流水线的所有任务 | | list_pipeline_trigger_jobs | 列出触发下游流水线的任务 | | get_pipeline_job | 获取任务详情 | | get_pipeline_job_output | 获取任务日志输出 | | play_pipeline_job | 运行手动任务 | | retry_pipeline_job | 重试失败的任务 | | cancel_pipeline_job | 取消运行中的任务 |

5️⃣ 项目管理（14 个）⚠️ 完整模式

| 工具名称 | 功能说明 | |---------|---------| | 命名空间 | | | list_namespaces | 列出所有命名空间 | | get_namespace | 获取命名空间详情 | | verify_namespace | 验证命名空间路径是否存在 | | 标签管理 | | | list_labels | 列出项目标签 | | get_label | 获取单个标签 | | create_label | 创建新标签 | | update_label | 更新标签 | | delete_label | 删除标签 | | 迭代管理 | | | list_group_iterations | 列出群组迭代 | | 用户管理 | | | get_users | 根据用户名获取用户详情 | | 通用评论 | | | create_note | 创建通用评论（Issue/MR） |

6️⃣ 里程碑管理（9 个）⚠️ 完整模式

| 工具名称 | 功能说明 | |---------|---------| | list_milestones | 列出里程碑 | | get_milestone | 获取里程碑详情 | | create_milestone | 创建里程碑 | | edit_milestone | 编辑里程碑 | | delete_milestone | 删除里程碑 | | get_milestone_issue | 获取里程碑关联的 Issue | | get_milestone_merge_requests | 获取里程碑关联的 MR | | promote_milestone | 提升里程碑阶段 | | get_milestone_burndown_events | 获取里程碑燃尽图事件 |

注意：需要设置 USE_MILESTONE=true 启用。

7️⃣ Wiki 文档（5 个）⚠️ 完整模式

| 工具名称 | 功能说明 | |---------|---------| | list_wiki_pages | 列出 Wiki 页面 | | get_wiki_page | 获取 Wiki 页面内容 | | create_wiki_page | 创建 Wiki 页面 | | update_wiki_page | 更新 Wiki 页面 | | delete_wiki_page | 删除 Wiki 页面 |

注意：需要设置 USE_GITLAB_WIKI=true 启用。

8️⃣ 发布管理（7 个）⚠️ 完整模式

| 工具名称 | 功能说明 | |---------|---------| | list_releases | 列出所有发布版本 | | get_release | 根据标签获取发布详情 | | create_release | 创建新发布版本 | | update_release | 更新发布版本 | | delete_release | 删除发布版本 | | create_release_evidence | 创建发布证据（Premium/Ultimate） | | download_release_asset | 下载发布资产文件 |

9️⃣ 其他功能（5 个）⚠️ 完整模式

| 工具名称 | 功能说明 | |---------|---------| | 附件管理 | | | upload_markdown | 上传文件用于 Markdown 引用 | | download_attachment | 下载上传的附件 | | 事件追踪 | | | list_events | 列出当前用户的所有事件 | | get_project_events | 列出项目的可见事件 | | 高级功能 | | | execute_graphql | 执行 GitLab GraphQL 查询 |

| 工具名称 | 功能说明 | |---------|---------|

💡 使用示例

场景 1：让 AI 创建功能分支并提交代码

对话示例：

你：帮我创建一个名为 feature/user-login 的分支，基于 main 分支
AI：✓ 已创建分支 feature/user-login

你：在这个分支上创建文件 src/components/Login.tsx，内容是一个简单的登录组件
AI：✓ 已创建文件 src/components/Login.tsx，提交消息：Add Login component

使用工具：

create_branch
create_or_update_file

场景 2：自动化代码审查

对话示例：

你：查看 MR !123 的代码变更，帮我审查一下
AI：[分析代码差异]
   发现以下问题：
   1. src/utils/auth.ts:45 - 缺少错误处理
   2. src/api/user.ts:23 - 建议使用 async/await
   
   要我在 MR 上添加评论吗？

使用工具：

get_merge_request
get_merge_request_diffs
create_merge_request_thread

场景 3：CI/CD 监控与自动重试

对话示例：

你：检查最新的 Pipeline 状态，如果失败了就重试
AI：✓ Pipeline #456 状态：failed
   失败原因：test-job 超时
   ✓ 已重试 Pipeline #456

使用工具：

list_pipelines
get_pipeline
retry_pipeline

场景 4：批量创建 Issue

对话示例：

你：根据以下需求创建 Issue：
   - 实现用户登录功能
   - 添加密码重置功能
   - 完善权限管理
   
AI：✓ 已创建 3 个 Issue：
   #101: 实现用户登录功能
   #102: 添加密码重置功能
   #103: 完善权限管理

使用工具：

create_issue（循环调用）

场景 5：项目初始化

对话示例：

你：创建一个新项目 my-awesome-app，初始化 README 和 .gitignore
AI：✓ 已创建项目 my-awesome-app (ID: 789)
   ✓ 已添加 README.md
   ✓ 已添加 .gitignore（Node.js 模板）

使用工具：

create_repository
push_files

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

GitLab MCP Server

📦 快速开始

🔐 认证方式

个人访问令牌（推荐）

⚠️ 版本管理

🎯 Cursor 优化模式

⚙️ 配置说明

必需配置

常用配置

📦 完整功能模式

1️⃣ 代码管理（16 个）✅ Cursor 模式包含

2️⃣ 合并请求（30 个）

3️⃣ 问题管理（13 个）⚠️ 完整模式

4️⃣ CI/CD 流水线（12 个）⚠️ 完整模式

5️⃣ 项目管理（14 个）⚠️ 完整模式

6️⃣ 里程碑管理（9 个）⚠️ 完整模式

7️⃣ Wiki 文档（5 个）⚠️ 完整模式

8️⃣ 发布管理（7 个）⚠️ 完整模式

9️⃣ 其他功能（5 个）⚠️ 完整模式

💡 使用示例

场景 1：让 AI 创建功能分支并提交代码

场景 2：自动化代码审查

场景 3：CI/CD 监控与自动重试

场景 4：批量创建 Issue

场景 5：项目初始化