gitlab-mcp-server

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';

// Path to the GitLab MCP Server binary
const serverPath = join(require.resolve('@piatra-open-source/gitlab-mcp-server'), '..', '..', 'bin', 'gitlab-mcp-server');

// Start the 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	移除议题之间的链接

使用示例

// Example: Create a repository in a specific group
const repo = await claude.callMcp("gitlab", "create_repository", {
  name: "my-new-project",
  description: "A new project created via MCP",
  visibility: "private",
  initialize_with_readme: true,
  namespace_id: "12345678"  // Group ID where the project should be created
});

// Example: Change project visibility
const updatedRepo = await claude.callMcp("gitlab", "update_project", {
  project_id: "12345678",
  visibility: "private"
});

// Example: Delete a project
const deleteResult = await claude.callMcp("gitlab", "delete_project", {
  project_id: "12345678"
});

// Example: Get all issues with time tracking stats
const issues = await claude.callMcp("gitlab", "get_issues", {
  project_id: "12345678",
  state: "opened",
  with_time_stats: true
});

// Example: Add spent time to an issue
const timeStats = await claude.callMcp("gitlab", "add_spent_time", {
  project_id: "12345678", 
  issue_iid: 42,
  duration: "1h 30m" // Format: Xh Ym
});

// Example: Get all comments on an issue
const notes = await claude.callMcp("gitlab", "get_notes", {
  project_id: "12345678",
  issue_iid: 42,
  sort: "desc",
  order_by: "created_at"
});

// Example: Update an issue
const updatedIssue = await claude.callMcp("gitlab", "update_issue", {
  project_id: "12345678",
  issue_iid: 42,
  title: "Updated issue title",
  description: "This is the updated description"
});

// Example: Create a label
const newLabel = await claude.callMcp("gitlab", "create_project_label", {
  project_id: "12345678",
  name: "enhancement",
  color: "#428BCA",
  description: "Enhancement requests"
});

// Example: Add labels to an issue
const issueWithLabels = await claude.callMcp("gitlab", "add_labels_to_issue", {
  project_id: "12345678",
  issue_iid: 42,
  labels: ["bug", "enhancement"]
});

// Example: Create a milestone
const milestone = await claude.callMcp("gitlab", "create_project_milestone", {
  project_id: "12345678",
  title: "v1.0 Release",
  description: "First stable release",
  due_date: "2025-06-30"
});

// Example: Assign users to an issue
const assignedIssue = await claude.callMcp("gitlab", "assign_issue", {
  project_id: "12345678",
  issue_iid: 42,
  assignee_ids: [123, 456]
});

// Example: Create a link between issues
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 should be a valid file path” 错误

如果遇到错误 GitLab API error (400): Bad Request - file_path should be a valid file path，可能有以下几种原因：

1. 文件路径格式：GitLab 要求文件路径有效且格式正确。请确保文件路径：

   • 不包含 *、?、[、] 等无效字符。
   • 使用正斜杠（/），而非反斜杠（\）。
   • 已正确进行 URL 编码（此库会处理）。

2. 大小写敏感：GitLab 文件路径区分大小写。请确保路径大小写与现有文件完全一致。

3. 仓库结构：更新文件时，文件路径必须存在于仓库结构中；新建文件时，路径必须有效。

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

其他常见问题

• 身份验证失败：请确保你的 GITLAB_PERSONAL_ACCESS_TOKEN 具有所需权限。
• 权限被拒绝：请确保你拥有访问仓库和群组的适当权限。
• 速率限制：GitLab API 有速率限制。超出限制时，可能会暂时阻止你访问。

许可证

MIT

致谢

此项目是 Anthropic 最初发布的 Model Context Protocol GitLab server 的增强版本，并根据 MIT 许可证进行了修改和扩展。