AI导哈

GitLab MCP连接器

一个基于Go的GitLab MCP连接器，为AI助手提供自然语言交互的GitLab操作接口，支持项目、合并请求、CI/CD等全面管理。

  • by nguyenvanduocit
  • Go
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 nguyenvanduocit/gitlab-mcp

使用说明

GitLab MCP

GitLab的一个全面的基于Go的MCP（模型上下文协议）连接器，使Claude等AI助手能够与GitLab存储库、项目和工作流无缝交互。该工具为AI模型提供了一个强大的界面，通过自然语言执行全面的GitLab操作。

为什么

虽然GitLab提供各种API集成，但我们的MCP实现提供 卓越的AI原生交互和全面的工作流管理我们构建了这个连接器，以解决开发人员和项目经理在通过人工智能助手与GitLab合作时面临的真正挑战。

主要优势：

  • 全面的GitLab集成：完全访问项目、合并请求、管道、提交、CI/CD作业和用户管理
  • AI优化界面：专为与人工智能助手的自然语言交互而设计
  • 现实世界工作流焦点：旨在解决实际的日常问题，如代码审查、CI/CD监控和项目管理
  • 提高生产率：无缝集成，允许AI在不切换上下文的情况下帮助GitLab操作
  • 开发者友好：为实际开发工作流程设计的工具，而不仅仅是基本的API调用

🚀 功能概述

📁 项目和存储库管理

  • 列出并探索项目 具有详细的信息和访问级别
  • 获取文件内容 来自任何支持分支/提交的存储库
  • 浏览存储库结构 并浏览代码库
  • 访问项目元数据 包括统计和配置

🔀 合并请求操作

  • 列出合并请求 按状态、作者和目标分支进行过滤
  • 获取详细的MR信息 包括变更、讨论和批准
  • 创建新的合并请求 带有自定义标题和描述
  • 对合并请求的评论 并管理讨论
  • 监视合并请求状态 并审查进展情况
  • 获取MR管道和提交 进行全面审查
  • 重新设置合并请求的基础 需要时

🔄 管道和CI/CD管理

  • 列出并分析管道 带有状态和持续时间信息
  • 获取详细的管道信息 包括作业和工件
  • 触发新管道 使用自定义变量
  • 监控管道执行 以及作业详细信息
  • 跟踪CI/CD性能 跨项目

💼 作业管理

  • 列出项目和管道作业 具有过滤功能
  • 获取详细的工作信息 包括日志和工件
  • 取消正在运行的作业 需要时
  • 重试失败的作业 为了快速恢复
  • 监控作业状态 跨管道

📝 提交和历史跟踪

  • 搜索并列出提交 具有作者、日期和邮件筛选功能
  • 获取详细的提交信息 包括变化和统计数据
  • 按作者和文件路径搜索提交 用于目标分析
  • 对提交的评论 用于代码审查
  • 樱桃选择和恢复提交 用于分行管理
  • 跟踪存储库历史记录 以及发展进展

🌊 Git流工作流支持

  • 创建发布分支 遵循Git Flow约定
  • 创建要素分支 具有适当的命名
  • 创建修补程序分支 紧急修复
  • 完成发布 通过创建合并请求来开发和掌握
  • 完成功能 通过创建合并请求来开发
  • 完成修补程序 通过向两个分支创建合并请求
  • 列出Git流分支 按类型（功能、版本、修补程序）

👥 用户和组管理

  • 查看用户贡献事件 和活动流
  • 列出组成员 以及他们的角色
  • 列出可访问的组 具有过滤选项
  • 跟踪用户贡献 跨项目
  • 监控团队活动 以及合作

🔐 变量和安全管理

  • 列出组变量 有安全信息
  • 创建和更新组变量 适当界定范围
  • 管理可变安全 （保护、遮蔽、未经处理）
  • 删除变量 当不再需要时
  • 处理特定于环境的变量

🚀 部署和令牌管理

  • 列出部署令牌 针对项目和团体
  • 创建部署令牌 具有特定范围
  • 管理令牌权限 以及到期
  • 删除令牌 当不再需要时
  • 处理项目和组级别的令牌

🔍 高级搜索功能

  • 全局搜索 跨所有GitLab内容
  • 组特定搜索 组织内部
  • 项目特定搜索 取得有针对性的结果
  • 按范围搜索 （项目、合并请求、提交、用户、代码）
  • 专业搜索工具 对于问题、合并请求、提交和代码

🚀 快速入门指南

先决条件

在开始之前，您需要：

  1. GitLab账号 可以访问您的GitLab实例（GitLab.com或自托管）
  2. 个人访问令牌 来自GitLab（我们会帮你得到这个）
  3. Cursor IDE 与Claude整合

第一步：获取您的GitLab个人访问令牌

  1. 转到您的GitLab实例→ 用户设置 → 访问令牌
  2. 点击 “添加新令牌”
  3. 给它起个名字，比如“GitLab MCP连接器”
  4. 选择范围： api, read_user, read_repository, write_repository
  5. 设置到期日期（可选）
  6. 点击 “创建个人访问令牌”
  7. 复制令牌 （你不会再看到它了！）

步骤2：选择安装方法

我们建议 码头工人 最简单的设置：

🐳 选项A:Docker（推荐）

# Pull the latest image
docker pull ghcr.io/nguyenvanduocit/gitlab-mcp:latest

# Test it works (replace with your details)
docker run --rm \
  -e GITLAB_URL=https://gitlab.com \
  -e GITLAB_TOKEN=your-personal-access-token \
  ghcr.io/nguyenvanduocit/gitlab-mcp:latest

📦 选项B：下载二进制文件

  1. 首选 GitHub 发布
  2. 为您的平台下载：
    • macOS: gitlab-mcp_darwin_amd64
    • Linux: gitlab-mcp_linux_amd64
    • 视窗: gitlab-mcp_windows_amd64.exe
  3. 使其可执行（macOS/Linux）：
    chmod +x gitlab-mcp_*
sudo mv gitlab-mcp_* /usr/local/bin/gitlab-mcp

🛠️ 选项C：从源代码构建

go install github.com/nguyenvanduocit/gitlab-mcp@latest

步骤3：配置游标

  1. 打开的游标
  2. 转到“设置” → 特性 → 模型上下文协议
  3. 添加新的MCP服务器 采用此配置：

对于Docker用户：

{
  "mcpServers": {
    "gitlab": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GITLAB_URL=https://gitlab.com",
        "-e", "GITLAB_TOKEN=your-personal-access-token",
        "ghcr.io/nguyenvanduocit/gitlab-mcp:latest"
      ]
    }
  }
}

对于二进制用户：

{
  "mcpServers": {
    "gitlab": {
      "command": "/usr/local/bin/gitlab-mcp",
      "env": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_TOKEN": "your-personal-access-token"
      }
    }
  }
}

对于自托管GitLab：

替换 https://gitlab.com 使用您的GitLab实例URL（例如。， https://gitlab.yourcompany.com)

步骤4：测试您的设置

  1. 重新启动游标 完全
  2. 打开新聊天 与克劳德
  3. 尝试以下测试命令:
List my GitLab groups

Show me recent merge requests in my projects

What's the status of the latest pipeline?

如果你看到GitLab的数据， 祝贺 🎉 你们都准备好了。

🔧 高级配置

使用环境文件

创建一个 .env 文件以便于管理：

# .env file
GITLAB_URL=https://gitlab.com
GITLAB_TOKEN=your-personal-access-token

然后使用它：

# With binary
gitlab-mcp -env .env

# With Docker
docker run --rm -i --env-file .env ghcr.io/nguyenvanduocit/gitlab-mcp:latest

HTTP开发模式

对于开发和测试，您可以在HTTP模式下运行：

# Start HTTP server on port 3000
gitlab-mcp -env .env -http_port 3000

然后配置Cursor：

{
  "mcpServers": {
    "gitlab": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

🎯 用法示例

配置后，您可以让Claude使用自然语言帮助完成GitLab任务：

项目和存储库管理

  • “显示我的所有GitLab组”
  • 在“我的团队”组中列出项目
  • “从项目X的主分支获取README文件”
  • “Z项目最近有什么变化？”

合并请求操作

  • “显示ABC项目中所有打开的合并请求”
  • “从功能分支创建合并请求以进行开发”
  • “ABC项目中123号MR的状态如何？”
  • “在合并请求#456中添加一条注释，说明'LGTM'”
  • “显示MR#789的管道状态”

管道和CI/CD管理

  • “项目X中最新管道的状态如何？”
  • “在开发分支上触发新的管道”
  • “显示上周失败的管道”
  • “列出项目Y中所有正在运行的作业”
  • “取消项目Z中的作业#123”

Git流工作流

  • “为1.2.0版本创建发布分支”
  • “创建一个名为用户身份验证的功能分支”
  • “完成1.2.0版本并创建合并请求”
  • “列出项目中的所有功能分支”

搜索与发现

  • “在所有项目中搜索包含‘bug修复’的提交”
  • “在组X中查找与身份验证相关的合并请求”
  • “在项目Y中搜索包含“API_KEY”的代码”
  • “显示组Z中的所有用户”

变量和安全管理

  • “列出组‘生产’中的所有变量”
  • “在组X中创建新变量DATABASE_URL”
  • “显示项目Y的部署令牌”

发展见解

  • “显示作者约翰最近的作品”
  • “今天对主要分支机构做出了哪些承诺？”
  • “列出消息中带有'fix'的所有提交”
  • “显示开发团队的用户活动”

🛠️ 可用工具参考

项目工具

  • list_projects -列出组中的项目
  • get_project -获取详细的项目信息

合并请求工具

  • list_mrs -使用筛选功能列出合并请求
  • get_mr_details -获取详细的MR信息
  • create_mr -创建新的合并请求
  • create_mr_note -添加评论以合并请求
  • list_mr_comments -列出所有MR评论
  • get_mr_pipelines -获取MR管道信息
  • get_mr_commits -获取MR提交历史记录
  • create_mr_pipeline -触发新的MR管道
  • rebase_mr -重新设置合并请求的基础

存储库工具

  • get_file_content -从存储库获取文件内容
  • list_commits -带有日期过滤的列表提交
  • get_commit_details -获取详细的提交信息
  • search_commits -按作者/路径/日期搜索提交
  • get_commit_comments -获取提交评论
  • post_commit_comment -在提交中添加注释
  • get_commit_merge_requests -获取与提交相关的MR
  • cherry_pick_commit -樱桃采摘承诺其他分支
  • revert_commit -恢复提交

管道工具

  • list_pipelines -列出项目管道
  • get_pipeline -获取详细的管道信息
  • trigger_pipeline -使用变量触发新管道

作业工具

  • list_project_jobs -列出所有项目作业
  • list_pipeline_jobs -列出特定管道的作业
  • get_job -获取详细的工作信息
  • cancel_job -取消正在运行的作业
  • retry_job -重试失败的作业

Git流工具

  • gitflow_create_release -创建发布分支
  • gitflow_finish_release -使用MR完成发布
  • gitflow_create_feature -创建要素分支
  • gitflow_finish_feature -使用MR完成功能
  • gitflow_create_hotfix -创建修补程序分支
  • gitflow_finish_hotfix -使用MR完成修补程序
  • gitflow_list_branches -列出Git流分支

用户和组工具

  • list_user_contribution_events -列出用户活动
  • list_group_users -列出组成员
  • list_groups -列出可访问的组

可变工具

  • list_group_variables -列出组变量
  • get_group_variable -获取特定变量的详细信息
  • create_group_variable -创建新变量
  • update_group_variable -更新现有变量
  • remove_group_variable -删除变量

部署工具

  • list_all_deploy_tokens -列出所有部署令牌（管理员）
  • list_project_deploy_tokens -列出项目部署令牌
  • get_project_deploy_token -获取项目令牌详细信息
  • create_project_deploy_token -创建项目令牌
  • delete_project_deploy_token -删除项目令牌
  • list_group_deploy_tokens -列出组部署令牌
  • get_group_deploy_token -获取组令牌详细信息
  • create_group_deploy_token -创建组令牌
  • delete_group_deploy_token -删除组令牌

搜索工具

  • search_global -搜索所有GitLab
  • search_group -在特定组内搜索
  • search_project -在特定项目中搜索
  • search_issues_global -全球问题搜索
  • search_merge_requests_global -全球MR搜索
  • search_commits_global -全局提交搜索
  • search_code_global -全球代码搜索

🛠️ 故障排除

常见问题

❌ “连接失败”或“身份验证错误”

  • 仔细检查你的 GITLAB_URL （应包含https://）
  • 验证您的个人访问令牌是否正确且未过期
  • 确保您的令牌具有所需的作用域(api, read_user, read_repository, write_repository)

❌ “未找到MCP服务器”

  • 添加配置后完全重新启动Cursor
  • 检查游标设置中的MCP配置语法
  • 验证二进制路径是否正确（对于二进制安装）

❌ “权限被拒绝”错误

  • 确保您的GitLab帐户可以访问您尝试访问的项目
  • 检查您的个人访问令牌是否具有必要的权限
  • 验证您使用的是正确的GitLab实例URL

❌ “超出费率限制”

  • GitLab有API速率限制；请稍候，然后重试
  • 考虑使用更具体的查询来减少API调用

❌ “缺少必需的环境变量”

  • 确保两者 GITLAB_URL 和 GITLAB_TOKEN 已设置
  • 检查是否从.env文件中正确加载了环境变量

获取帮助

  1. 检查日志：跑步 -http_port 查看详细的错误消息
  2. 测试您的凭据：尝试步骤2中的Docker测试命令
  3. 验证游标配置：应用程序将向您显示要使用的确切配置
  4. 检查GitLab权限：确保您的令牌可以访问所需的资源

📚 发展

为了地方发展和贡献：

# Clone the repository
git clone https://github.com/nguyenvanduocit/gitlab-mcp.git
cd gitlab-mcp

# Create .env file with your credentials
cp .env.example .env
# Edit .env with your details

# Run in development mode
just dev
# or
go run main.go -env .env

# Build the project
just build

# Install locally
just install

# Test with MCP inspector (if running in HTTP mode)
npx @modelcontextprotocol/inspector http://localhost:3000/mcp

项目结构

gitlab-mcp/
├── bin/          # Compiled binaries
├── tools/        # Tool implementations
│   ├── projects.go      # Project management tools
│   ├── merge_requests.go # MR management tools
│   ├── repositories.go  # Repository and commit tools
│   ├── pipelines.go     # Pipeline management tools
│   ├── job.go          # CI/CD job tools
│   ├── flow.go         # Git Flow workflow tools
│   ├── users.go        # User management tools
│   ├── groups.go       # Group management tools
│   ├── variable.go     # Variable management tools
│   ├── deploy.go       # Deployment token tools
│   └── search.go       # Search functionality tools
├── util/         # Utility functions
├── main.go       # Application entry point
├── go.mod        # Go module definition
├── justfile      # Build automation
└── README.md     # This file

CLI使用情况

除了MCP服务器之外， gitlab-mcp 提供独立的CLI二进制文件(gitlab-cli)用于直接终端使用——不需要MCP客户端。

安装

just install-cli
# or
go install github.com/nguyenvanduocit/gitlab-mcp/cmd/gitlab-cli@latest

快速开始

export GITLAB_URL=https://gitlab.com
export GITLAB_TOKEN=your-access-token
# or
gitlab-cli --env .env <command> [flags]

命令

命令 描述
list-projects 列出GitLab项目
list-mrs 列出合并请求
list-pipelines 列出管道
list-branches 列出分支
list-jobs 列出CI/CD作业
list-users 列出组成员
list-groups 列出组
manage-variable 管理CI/CD变量
trigger-pipeline 触发管道
search 在GitLab上搜索

示例

# List projects
gitlab-cli list-projects --search my-repo

# List open MRs
gitlab-cli list-mrs --project-id 123 --state opened

# Trigger pipeline
gitlab-cli trigger-pipeline --project-id 123 --ref main

# JSON output
gitlab-cli list-projects --output json | jq '.[].path_with_namespace'

旗帜

每个命令都接受：

  • --env string --通往 .env 文件
  • --output string --输出格式： text （默认）或 json

🤝 贡献

我们欢迎捐款！以下是如何开始：

  1. 分叉存储库
  2. 创建功能分支 (git checkout -b feature/amazing-feature)
  3. 提交您的更改 (git commit -m 'feat: add some amazing feature')
  4. 推到分支 (git push origin feature/amazing-feature)
  5. 打开拉取请求

贡献指南

  • 跟随 常规承诺 用于提交消息
  • 为新功能添加测试
  • 根据需要更新文档
  • 提交前确保所有测试通过

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

需要帮助？ 查看我们的 更改日志.md 获取最新更新或在GitHub上发布问题。

安装

自制（macOS/Linux）

brew install nguyenvanduocit/tap/gitlab-mcp

相关 MCP