GitLab MCP 服务器

一个用于与 GitLab 仓库进行交互并具有增强功能的模型上下文协议（MCP）服务器。

概述

此 MCP 服务器允许 AI 助手（如 Claude）与 GitLab 仓库进行交互，管理项目、问题、合并请求等。它扩展了原始实现，增加了额外的端点并改进了错误处理。

特性

• 项目管理

  • 创建新仓库（改进了组命名空间支持）
  • 更新项目设置（包括可见性）
  • 删除项目
  • 分叉项目
  • 搜索仓库

• 文件操作

  • 获取文件内容
  • 创建或更新文件
  • 批量提交多个文件

• 仓库管理

  • 创建分支
  • 创建问题
  • 创建合并请求

• 问题和时间跟踪

  • 使用过滤选项获取问题
  • 获取详细的问题信息
  • 管理时间跟踪（估计时间和已花费时间）
  • 查看时间跟踪统计
  • 更新问题属性
  • 关闭和重新打开问题

• 注释（评论）

  • 获取问题评论
  • 创建新的评论
  • 更新现有评论
  • 删除评论

• 标签管理

  • 获取项目标签
  • 创建、更新和删除标签
  • 将标签添加到问题中
  • 从问题中移除标签

• 里程碑管理

  • 获取项目里程碑
  • 创建新的里程碑

• 用户分配

  • 将用户分配给问题
  • 从问题中移除分配的用户

• 问题关系

  • 在问题之间创建链接
  • 删除问题之间的链接

安装

全局安装

npm install -g @piatra-open-source/gitlab-mcp-server

项目安装

npm install @piatra-open-source/gitlab-mcp-server

使用方法

环境变量

你需要设置以下环境变量：

• GITLAB_PERSONAL_ACCESS_TOKEN：你的 GitLab 个人访问令牌，具有适当的权限
• GITLAB_API_URL（可选）：如果你不使用 gitlab.com，则需要自定义 GitLab API URL（默认值为 'https://gitlab.com/api/v4'）

运行服务器

export GITLAB_PERSONAL_ACCESS_TOKEN='your_token_here'
gitlab-mcp-server

或者在你的应用中：

import { execFileSync } from 'child_process';
import { join } from 'path';

// GitLab MCP 服务器二进制文件路径
const serverPath = join(require.resolve('@piatra-open-source/gitlab-mcp-server'), '..', '..', 'bin', 'gitlab-mcp-server');

// 启动服务器
const childProcess = execFileSync(serverPath, {
  env: {
    ...process.env,
    GITLAB_PERSONAL_ACCESS_TOKEN: 'your_token_here'
  }
});

API 参考

函数

函数名称	描述
create_repository	创建一个新的 GitLab 项目
update_project	更新项目设置，包括可见性
delete_project	删除 GitLab 项目
search_repositories	搜索 GitLab 项目
get_file_contents	获取文件或目录的内容
create_or_update_file	创建或更新单个文件
push_files	批量提交多个文件
create_branch	创建新的分支
fork_repository	分叉项目
create_issue	创建新的问题
create_merge_request	创建新的合并请求
get_issues	使用过滤选项获取项目中的问题
get_issue	获取带有详细信息的单个问题
get_issue_time_stats	获取问题的时间跟踪统计
set_time_estimate	设置问题的时间估计
reset_time_estimate	重置问题的时间估计
add_spent_time	向问题添加已花费时间
reset_spent_time	重置问题的已花费时间
get_notes	获取问题的评论/注释
create_note	在问题上创建评论
update_note	更新现有的评论
delete_note	从问题中删除评论
update_issue	更新各种问题属性
close_issue	关闭问题
reopen_issue	重新打开已关闭的问题
get_project_labels	获取项目的全部标签
create_project_label	为项目创建新的标签
update_project_label	更新现有的标签
delete_project_label	从项目中删除标签
add_labels_to_issue	将特定标签添加到问题中
remove_labels_from_issue	从问题中移除特定标签
get_project_milestones	获取项目的全部里程碑
create_project_milestone	为项目创建新的里程碑
assign_issue	将用户分配给问题
unassign_issue	移除所有分配给问题的用户
create_issue_link	在两个问题之间创建链接
delete_issue_link	移除问题之间的链接

示例用法

// 示例：在特定组中创建一个仓库
const repo = await claude.callMcp("gitlab", "create_repository", {
  name: "my-new-project",
  description: "通过 MCP 创建的新项目",
  visibility: "private",
  initialize_with_readme: true,
  namespace_id: "12345678"  // 应该创建项目的组ID
});

// 示例：更改项目可见性
const updatedRepo = await claude.callMcp("gitlab", "update_project", {
  project_id: "12345678",
  visibility: "private"
});

// 示例：删除项目
const deleteResult = await claude.callMcp("gitlab", "delete_project", {
  project_id: "12345678"
});

// 示例：获取带有时间跟踪统计的所有问题
const issues = await claude.callMcp("gitlab", "get_issues", {
  project_id: "12345678",
  state: "opened",
  with_time_stats: true
});

// 示例：向问题添加已花费时间
const timeStats = await claude.callMcp("gitlab", "add_spent_time", {
  project_id: "12345678", 
  issue_iid: 42,
  duration: "1h 30m" // 格式：Xh Ym
});

// 示例：获取问题上的所有评论
const notes = await claude.callMcp("gitlab", "get_notes", {
  project_id: "12345678",
  issue_iid: 123,
  sort: "desc",
  order_by: "created_at"
});

// 示例：更新问题
const updatedIssue = await claude.callMcp("gitlab", "update_issue", {
  project_id: "12345678",
  issue_iid: 42,
  title: "更新的问题标题",
  description: "这是更新后的描述"
});

// 示例：创建标签
const newLabel = await claude.callMcp("gitlab", "create_project_label", {
  project_id: "12345678",
  name: "enhancement",
  color: "#428BCA",
  description: "增强请求"
});

// 示例：将标签添加到问题中
const issueWithLabels = await claude.callMcp("gitlab", "add_labels_to_issue", {
  project_id: "12345678",
  issue_iid: 42,
  labels: ["bug", "enhancement"]
});

// 示例：创建里程碑
const milestone = await claude.callMcp("gitlab", "create_project_milestone", {
  project_id: "12345678",
  title: "v1.0 发布",
  description: "第一个稳定版本",
  due_date: "2025-06-30"
});

// 示例：将用户分配给问题
const assignedIssue = await claude.callMcp("gitlab", "assign_issue", {
  project_id: "12345678",
  issue_iid: 42,
  assignee_ids: [123, 456]
});

// 示例：在问题之间创建链接
const issueLink = await claude.callMcp("gitlab", "create_issue_link", {
  project_id: "12345678",
  issue_iid: 42,
  target_project_id: "12345678",
  target_issue_iid: 43,
  link_type: "relates_to"
});

相对于原始实现的改进

此实现相对于原始的 MCP GitLab 服务器包括几个增强：

1. 全面的API端点：

   • delete_project：正确地删除 GitLab 项目
   • update_project：更新项目设置，包括可见性
   • get_issues 和 get_issue：使用过滤选项检索问题
   • 时间跟踪端点：设置/重置估计时间和已花费时间
   • 注释端点：创建、读取、更新、删除评论
   • 标签管理：创建、检索、更新和删除标签
   • 里程碑管理：获取里程碑并创建新的里程碑
   • 用户分配：将用户分配给问题并取消分配
   • 问题关系：创建和删除问题之间的链接

2. 改进的 namespace_id 处理：

   • 正确支持在组命名空间中创建项目
   • 验证并传递 namespace_id 到 GitLab API

3. 增强的错误处理：

   • 包含 API 响应数据的详细错误消息
   • 改进输入参数的验证
   • 对身份验证和权限问题提供更好的反馈

4. 更新的文档：

   • 清晰地记录所有支持的参数
   • 更完整的类型定义

故障排除

"file_path 应该是一个有效的文件路径" 错误

如果你遇到错误 GitLab API 错误 (400): Bad Request - file_path 应该是一个有效的文件路径，可能的原因有：

1. 文件路径格式：GitLab 期望文件路径是有效且格式正确的。确保你的文件路径：

   • 不包含无效字符，如 *, ?, [, ] 等
   • 使用正斜杠 (/) 而不是反斜杠 (\)
   • 正确 URL 编码（由本库处理）

2. 大小写敏感：GitLab 文件路径是大小写敏感的。确保路径与现有文件的确切大小写匹配。

3. 仓库结构：文件路径必须存在于仓库结构中以进行更新，或对新文件有效。

4. 特殊字符：尽可能避免在文件名中使用特殊字符。如果需要使用字符如 #, ?, [, ]，请注意它们可能需要特殊处理。

其他常见问题

• 身份验证失败：确保你的 GITLAB_PERSONAL_ACCESS_TOKEN 具有必要的权限。
• 权限被拒绝：确保你对仓库和组具有适当的访问权限。
• 速率限制：GitLab API 有速率限制，如果超过限制可能会暂时阻止你的访问。

许可证

MIT

致谢

此项目是对 Anthropic 的原始 Model Context Protocol GitLab 服务器 的增强版，在 MIT 许可证下进行了修改和扩展。