GitLab项目管理工具

GitLab MCP服务器

也有俄语版本： README-ru.md

GitLab MCP服务器提供了直接从Claude Code、Code CLI和其他MCP客户端处理GitLab项目、合并请求和标签的工具。

目录

• 特性
• 需求
• 安装
  • 使用npx（推荐）
  • 使用Claude MCP命令行界面
  • 手动安装（开发）
• 开发与发布
  • GitHub操作工作流
  • 设置NPM_TOKEN
  • 发布过程
  • 手动构建和测试
• 运行服务器（stdio）
• 代码配置（推荐）
• Claude Code CLI的配置
• VS代码库配置
• MCP工具
  • 只读模式与写入模式
  • 工具使用指南
• 响应格式

特性

• 列出可用项目并获取详细的项目信息。
• 使用基于SemVer的下一版本标签计算查看存储库标签。
• 使用状态和更新日期筛选器列出合并请求。
• 使用新鲜度指示器获取合并请求详细信息（在24小时内合并）。
• 通过分页和筛选查看已更改的文件和合并请求的完整差异。
• 按标题和描述搜索合并请求。
• 列出具有活动跟踪和批处理操作的GitLab用户。
• 使用访问级别信息管理项目和组成员。
• 使用状态过滤器和日期范围监控CI/CD管道。
• 查看包含执行细节、工件和运行者信息的管道作业。
• 跟踪构建历史并分析跨项目的作业失败。

需求

• Node.js≥20
• 环境变量：
  • GITLAB_URL --GitLab实例库URL
  • GITLAB_TOKEN --个人访问令牌
    • 只读模式（默认）: read_api 和 read_repository 范围
    • 写入模式 （用于创建标签）： api 范围
  • GITLAB_READ_ONLY --可选，默认为 true 为了安全
    • 吃起来 false 启用写入操作（标记创建）
  • GITLAB_TIMEZONE --可选，日期/时间格式的时区（默认为 Europe/Moscow)
    • 示例： UTC, America/New_York, Asia/Tokyo, Europe/London
    • API响应中的所有日期都将在指定的时区进行格式化

安装

使用npx（推荐）

您可以直接使用npx运行服务器，而无需安装：

GITLAB_URL="https://gitlab.example.com" \
GITLAB_TOKEN="glpat-your-token-here" \
npx -y @vitalyostanin/gitlab-mcp@latest

使用Claude MCP命令行界面

使用Claude MCP CLI进行安装：

claude mcp add --scope user \
--env GITLAB_URL='https://gitlab.example.com' \
--env GITLAB_TOKEN='glpat-your-token-here' \
gitlab-mcp -- npx -y @vitalyostanin/gitlab-mcp@latest

范围选项：

• --scope user：为当前用户安装（所有项目）
• --scope project：仅为当前项目安装

移除：

claude mcp remove gitlab-mcp --scope user

手动安装（开发）

npm install
npm run build

开发与发布

GitHub操作工作流

该项目使用GitHub Actions进行持续集成和自动发布：

CI工作流(.github/workflows/ci.yml)

在每次推送和拉取请求时自动运行：

• 触发器：所有分支，所有拉取请求
• Node.js版本：20.x，22.x（矩阵测试）
• 步骤:
  1. 安装依赖项(npm ci)
  2. 运行门楣(npm run lint)
  3. 建设项目(npm run build)
  4. 验证构建工件（可执行文件检查）

发布工作流(.github/workflows/publish.yml)

创建新版本标记时自动运行：

• 触发：Git标签匹配 v* 模式（例如。， v0.1.0, v1.2.3)
• Node.js版本：20.x
• 步骤:
  1. 安装依赖项
  2. 建设项目
  3. 发布到npm注册表
  4. 创建GitHub版本

设置NPM_TOKEN

要启用自动发布到npm，您需要配置 NPM_TOKEN 秘密：

1. 生成npm访问令牌:

   • 首选 npmjs.com 并登录
   • 导航至 访问令牌 在您的帐户设置中
   • 点击 生成新令牌 → 经典代币
   • 选择 自动化 类型（用于CI/CD）
   • 复制生成的令牌

2. 将Secret添加到GitHub:

   • 转到您的GitHub存储库
   • 导航至 设置 → 秘密与变量 → 行动
   • 点击 新存储库机密
   • 姓名： NPM_TOKEN
   • 值：粘贴你的npm令牌
   • 点击 添加机密

发布过程

要创建新版本，请执行以下操作：

# 1. Update version in package.json and create git tag
npm version patch   # for 0.1.0 → 0.1.1
# or
npm version minor   # for 0.1.0 → 0.2.0
# or
npm version major   # for 0.1.0 → 1.0.0

# 2. Push the tag to GitHub
git push --follow-tags

# 3. GitHub Actions will automatically:
#    - Run tests and build
#    - Publish to npm
#    - Create GitHub Release

备注：The npm version 命令自动执行：

• 更新 package.json 和 package-lock.json
• 创建一个git commit，并显示类似“0.1.1”的消息
• 创建类似“v0.1.1”的git标签

手动构建和测试

# Install dependencies
npm install

# Build the project
npm run build

# Run linter
npm run lint

# Watch mode for development
npm run dev:watch

运行服务器（stdio）

GITLAB_URL="https://gitlab.example.com" \
GITLAB_TOKEN="glpat-example-token" \
node dist/index.js

代码配置（推荐）

增添 ~/.code/config.toml:

[mcp_servers.gitlab-mcp]
command = "npx"
args = ["-y", "@vitalyostanin/gitlab-mcp@latest"]

[mcp_servers.gitlab-mcp.env]
GITLAB_URL = "https://gitlab.example.com"
GITLAB_TOKEN = "glpat-your-token-here"
GITLAB_TIMEZONE = "Europe/Moscow"

Claude Code CLI的配置

使用此MCP服务器 Claude 代码命令行工具，您可以：

1. 使用Claude MCP命令行界面 -看 安装 以上章节
2. 手动配置 -添加到您的 ~/.claude.json 文件：

{
  "mcpServers": {
    "gitlab-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@vitalyostanin/gitlab-mcp@latest"],
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-your-token-here",
        "GITLAB_TIMEZONE": "Europe/Moscow",
        "GITLAB_USE_STRUCTURED_CONTENT": "false"
      }
    }
  }
}

注： 此配置使用npx运行已发布的包。对于当地发展，使用 "command": "node" 随着 "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"].

VS代码库配置

使用此MCP服务器 克莱恩 VS代码中的扩展名：

1. 打开安装了Cline扩展的VS代码
2. 单击Cline顶部导航中的MCP服务器图标
3. 选择“配置”选项卡，然后单击“配置MCP服务器”
4. 将以下配置添加到 cline_mcp_settings.json:

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "npx",
      "args": ["-y", "@vitalyostanin/gitlab-mcp@latest"],
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-your-token-here",
        "GITLAB_TIMEZONE": "Europe/Moscow",
        "GITLAB_USE_STRUCTURED_CONTENT": "false"
      }
    }
  }
}

注： 此配置使用npx运行已发布的包。对于当地发展，使用 "command": "node" 随着 "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"]The GITLAB_TIMEZONE 和 GITLAB_READ_ONLY 环境变量是可选的。

MCP工具

| gitlab_commits |带有过滤器和分页的项目列表提交（简短模式默认）。 | | gitlab_commit_details |获取SHA特定提交的详细信息。 | | gitlab_commit_diff |获取提交的diff文件（默认为简短模式；完全diff可选）。 | | gitlab_commit_statuses |列出提交的CI状态（按上下文/管道）。 |

只读模式与写入模式

默认情况下，GitLab MCP服务器在 只读模式 为了安全。这可以防止对GitLab存储库的意外修改。

只读模式（默认）

• 代币要求: read_api 和 read_repository 范围
• 可用操作：所有读取操作（列出项目、MR、标签、用户等）
• 配置：无需特殊配置（默认行为）

写模式

要启用写操作（当前：标记创建），您必须：

1. 生成新的GitLab令牌 随着 api 范围（而不是 read_api)

   • 转到GitLab→ 设置→ 访问令牌
   • 使用创建新令牌 api 范围
   • 注： api 范围包括读和写权限

2. 设置环境变量 GITLAB_READ_ONLY=false

3. 确保适当的权限：你至少需要 开发者 标记创建目标项目中的角色

写入模式的示例配置：

# ~/.code/config.toml
[mcp_servers.gitlab-mcp]
command = "npx"
args = ["-y", "@vitalyostanin/gitlab-mcp@latest"]
env = {
  "GITLAB_URL" = "https://gitlab.example.com",
  "GITLAB_TOKEN" = "glpat-your-api-scope-token",
  "GITLAB_READ_ONLY" = "false",
  "GITLAB_TIMEZONE" = "Europe/Moscow"
}

安全说明：写入模式允许服务器对存储库进行更改。仅在需要时启用它，并确保您的令牌得到妥善保护。

工具使用指南

项目工具

• gitlab_projects：使用可选筛选器（成员资格、存档状态、基本搜索）列出可用项目。用途 /api/v4/projects 终点。 用于：浏览可用项目，仅列出活动项目(archived: false)，或检查存档的存储库(archived: true).返回每个项目 archived 与其他元数据一起标记。

• gitlab_projects_search：使用GitLab Search API按关键字搜索特定项目。用途 /api/v4/search?scope=projects 终点。 用于：按名称或路径查找特定项目（例如“电报/服务”）。

主要区别: gitlab_projects 用于使用过滤器进行列表/浏览，而 gitlab_projects_search 使用搜索API提供有针对性的关键字搜索。

合并请求工具

• gitlab_merge_requests：使用筛选器（状态、日期范围）列出特定项目的合并请求。需要项目标识符。 用于：获取特定项目的所有MR，按州或更新日期过滤。

• gitlab_merge_requests_search：使用GitLab Search API按文本（标题、描述）搜索合并请求。可以跨所有项目或在特定项目内进行搜索。 用于：按项目关键字查找MR。

主要区别: gitlab_merge_requests 列出特定项目的MR，同时 gitlab_merge_requests_search 通过跨项目的文本搜索查找MR。

新鲜度标志

这 新鲜度标志 是由返回的布尔字段 gitlab_merge_request_details 它指示合并请求是“新的”还是最近合并的：

• 对于未合并的MR （国家是 opened 或 closed): fresh = true （始终被视为新鲜）
• 对于合并的MR:
  • fresh = true --合并在最后 24小时
  • fresh = false --已合并超过24小时前

使用案例：

• 识别可能需要注意的最近合并的更改
• 跟踪项目中的热门/最近的合并活动
• 在查看最近的更改时过滤掉旧的合并MR

示例响应：

{
  "mergeRequest": {
    "id": 123,
    "iid": 45,
    "title": "Add new feature",
    "state": "merged",
    "mergedAt": "2025-10-13T10:30:00Z",
    "fresh": true
  }
}

用户工具

• gitlab_users：列出所有具有可选过滤器（活动、阻止、搜索）的GitLab用户。返回基本用户信息，包括上次活动日期。 用于：浏览可用用户，按名称或用户名搜索用户，监控用户活动。

• gitlab_user_details：通过ID或用户名获取特定用户的详细信息。包括上次活动和登录日期。 用于：获取用户配置文件详细信息，检查用户状态，查看活动历史记录。

• gitlab_users_batch：一次获取多个用户的详细信息（批处理模式，最多50个用户）。针对具有并行API请求的批量操作进行了优化。返回用户数组和缺失用户的notFound数组。 用于：高效获取多个用户的详细信息，分析团队活动，批量用户信息检索。

• gitlab_current_user：获取有关当前用户（API令牌所有者）的信息。包括权限标志和2FA状态。 用于：验证身份验证，检查当前用户权限。

• gitlab_project_members：列出特定项目的成员及其访问级别（访客=10，报告者=20，开发人员=30，维护人员=40，所有者=50）。 用于：检查谁有权访问项目，查看访问级别，查找项目维护者。

• gitlab_group_members：列出组/命名空间的成员及其访问级别（访客=10，报告者=20，开发人员=30，维护人员=40，所有者=50）。 用于：检查组成员资格，查看组访问级别，查找组管理员。

主要特点:

• 所有与用户相关的工具包括 lastActivityOn 和 lastSignInAt 活动跟踪字段
• 批处理模式支持每个请求最多50个用户，以获得最佳性能
• 优雅地处理丢失的用户，而不会使整个批处理请求失败
• 访问级别以数字和人类可读的描述形式提供

标签工具

• gitlab_project_tags：列出基于SemVer的自动下一版本建议的存储库标签。返回所有包含提交信息的标签，标识最新的符合SemVer的标签，并建议下一个补丁版本。还提供了一个预填充的GitLab web UI URL，便于手动创建标签。

使用案例：

• 计划下一个版本
• 使用自动版本控制查看标签历史记录
• 获取创建下一个发布标签的快速链接

它是如何工作的：

• 解析所有遵循SemVer格式的标签（例如。， v1.2.3, 1.0.0)
• 将最高版本标识为当前版本
• 建议下一个补丁版本（例如。， v1.2.3 → v1.2.4)
• 生成GitLab UI URL： https://gitlab.example.com/project/-/tags/new?tag_name=v1.2.4&ref=master

示例响应：

{
  "project": "namespace/my-project",
  "tags": [
    { "name": "v1.2.3", "commitId": "abc123...", "authoredAt": "2025-01-10T10:30:00Z" },
    { "name": "v1.2.2", "commitId": "def456...", "authoredAt": "2025-01-05T14:20:00Z" }
  ],
  "versionInfo": {
    "currentTag": "v1.2.3",
    "suggestedNextTag": "v1.2.4",
    "createTagUrl": "https://gitlab.example.com/namespace/my-project/-/tags/new?tag_name=v1.2.4&ref=master"
  },
  "pagination": {
    "page": 1,
    "perPage": 50,
    "total": 150,
    "hasMore": true
  }
}

• gitlab_project_tag_create：以编程方式在GitLab项目存储库中创建一个新标签。 需要写入模式 -看 只读模式与写入模式 上面的部分。

要求：

• 写入模式已启用(GITLAB_READ_ONLY=false)
• GitLab代币 api 范围
• 至少 开发者 目标项目中的角色

参数：

• project （必填）：项目ID或路径（例如。， "namespace/project" 或 123)
• tagName （必填）：标签名称遵循SemVer格式（例如。， "v1.2.4" 或 "1.2.4")
• ref （可选）：分支名称或将SHA提交给标签（默认为 "master")
• message （可选）：标记消息/注释
• releaseDescription （可选）：版本描述（创建GitLab版本）

使用案例：

• 自动化CI/CD管道中的发布标记
• 成功构建后以编程方式创建标签
• 跨多个项目批量创建标签

工作流程建议：

1. 使用 gitlab_project_tags 检查现有标签并获取建议的下一个版本
2. 使用 gitlab_project_tag_create 创建新标记
3. 处理常见错误（标记已存在、权限不足、找不到引用）

示例用法：

{
  "project": "namespace/my-project",
  "tagName": "v1.2.4",
  "ref": "master",
  "message": "Release version 1.2.4",
  "releaseDescription": "### Features\n- Added new API endpoint\n- Improved performance"
}

示例响应：

{
  "project": "namespace/my-project",
  "tag": {
    "name": "v1.2.4",
    "message": "Release version 1.2.4",
    "target": "master",
    "commit": {
      "id": "abc123def456...",
      "message": "Merge branch 'feature/new-api'",
      "createdAt": "2025-10-14T10:30:00Z"
    },
    "release": {
      "tagName": "v1.2.4",
      "description": "### Features\n- Added new API endpoint\n- Improved performance"
    },
    "url": "https://gitlab.example.com/namespace/my-project/-/tags/v1.2.4"
  }
}

常见错误：

• 只读模式：默认情况下禁用标记创建。如上所述启用写入模式。
• 409冲突：标记已存在。检查现有标签 gitlab_project_tags.
• 403禁止：权限不足。确保您拥有开发人员+角色 api 范围令牌。
• 422无法处理：在存储库中找不到引用（分支/提交）。
• 400错误请求：标记名格式无效。必须遵循SemVer（例如。， v1.2.3).

管道和作业工具

管道和作业工具提供对GitLab CI/CD管道和作业信息的全面访问，使您能够监控构建状态、分析作业执行和跟踪管道历史。

• gitlab_pipelines：列出带有可选过滤器（参考、状态、日期）的项目管道。用途 /api/v4/projects/:id/pipelines 终点。 用于：浏览项目的管道，按分支或状态过滤（例如，主管道上的失败管道），监控CI/CD活动。

• gitlab_pipeline_details：获取特定管道的详细信息。 用于：查看完整的管道详细信息，包括持续时间和覆盖率，检查执行时间戳，获取管道URL。

• gitlab_pipeline_jobs：列出特定管道中的所有作业。 用于：分析流水线执行阶段，查看作业状态和持续时间，排除失败的流水线步骤。

• gitlab_project_jobs：列出项目中所有管道的所有作业。 用于：浏览项目范围内的作业历史记录，按作业状态（例如，所有失败的作业）过滤，分析CI/CD模式。

• gitlab_job_details：获取特定工作的详细信息。 用于：查看作业执行详细信息，检查工件和运行者信息，分析作业失败。

• gitlab_latest_pipeline：快速访问分支机构的最新管道。 用于：检查当前CI/CD状态，获取最新构建结果，监视分支运行状况。

主要特点:

• 所有管道和作业工具都支持分页（默认50，每页最多100）
• 目标搜索的状态过滤器（例如，“失败”、“正在运行”、“成功”）
• 全面的元数据，包括持续时间、时间戳和URL
• 与现有项目解决方案集成（按ID或路径）

管道状态:

• created, waiting_for_resource, preparing, pending -管道已排队或正在启动
• running -管道当前正在执行
• success -所有作业均已成功完成
• failed -一个或多个作业失败
• canceled -管道已手动取消
• skipped -管道被跳过（例如，由于分支规则）
• manual -管道需要手动触发
• scheduled -管道计划运行

作业状态:

• created, pending -作业正在等待开始
• running -作业当前正在执行
• success -作业已成功完成
• failed -作业失败
• canceled -作业已取消
• skipped -作业被跳过
• manual -作业需要手动触发
• scheduled -作业计划运行

工作流程示例:

1. 列出故障管道： gitlab_pipelines({ project: "my-project", status: "failed" })
2. 获取管道详细信息： gitlab_pipeline_details({ project: "my-project", pipelineId: 12345 })
3. 检查失败的作业： gitlab_pipeline_jobs({ project: "my-project", pipelineId: 12345, scope: ["failed"] })
4. 调查具体工作： gitlab_job_details({ project: "my-project", jobId: 67890 })

示例响应（gitlab_pipelines）:

{
  "project": "namespace/my-project",
  "pipelines": [
    {
      "id": 12345,
      "iid": 678,
      "status": "failed",
      "ref": "master",
      "sha": "abc123de",
      "createdAt": "2025-10-14T10:00:00Z",
      "duration": 320,
      "webUrl": "https://gitlab.example.com/namespace/my-project/-/pipelines/12345"
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 50,
    "total": 150,
    "hasMore": true
  }
}

示例响应（gitlab_job_details）:

{
  "project": "namespace/my-project",
  "job": {
    "id": 67890,
    "name": "test:unit",
    "stage": "test",
    "status": "failed",
    "duration": 45,
    "pipeline": {
      "id": 12345,
      "ref": "master",
      "status": "failed"
    },
    "artifacts": [
      {
        "fileType": "junit",
        "filename": "junit.xml",
        "size": 1024
      }
    ],
    "url": "https://gitlab.example.com/namespace/my-project/-/jobs/67890"
  }
}

响应格式

默认情况下，服务器只返回一个数据节点，通过以下方式控制 GITLAB_USE_STRUCTURED_CONTENT （默认值： "true").

• 当 true：工具仅返回MCP structuredContent 节点包含完整数据，并包含空数据 content: [] 以满足MCP打字。
• 当 false：工具仅返回MCP content 节点（单个 text 包含JSON字符串的项），并省略 structuredContent.

客户须知：

• Claude Code用户可以设置 GITLAB_USE_STRUCTURED_CONTENT="false" 如果客户端希望在 content 现场。
• 临床用户（VS Code）也可以将该标志设置为 "false" 如果需要，在服务器配置中。