AI导哈

GitLab仓库管理服务

一个用于与GitLab仓库交互的MCP服务器，提供项目、文件、问题、合并请求等全面管理功能。

  • by piatra-automation
  • JavaScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 piatra-automation/gitlab-mcp-server

使用说明

GitLab MCP服务器

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

概述

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

特性

  • 项目管理

    • 创建新的存储库（具有改进的组命名空间支持）
    • 更新项目设置（包括可见性）
    • 删除项目
    • Fork项目
    • 搜索存储库

  • 文件操作

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

  • 库管理

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

  • 问题和时间跟踪

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

  • 备注（注释）

    • 检索问题评论
    • 创建新评论
    • 更新现有评论
    • 删除评论

  • 标签管理

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

  • 里程碑管理

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

  • 用户分配

    • 为用户分配问题
    • 从问题中删除指定人员

  • 问题关系

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

安装

全球安装

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应该是有效的文件路径”错误

如果您遇到错误 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有速率限制，如果超过速率限制，可能会暂时阻止您的访问。

许可证

麻省理工学院

归因

此项目是原始项目的增强版本 模型上下文协议GitLab服务器 由Anthropic根据麻省理工学院的许可进行修改和扩展。

相关 MCP