GitLab MCP 服务器 - 开发者工具类MCP服务器

使用说明

项目简介

本项目是一个基于 Model Context Protocol (MCP) 的 GitLab 集成服务器，旨在作为大型语言模型（LLM）如 Claude 的插件，扩展 LLM 的能力，使其能够安全、便捷地访问和操作 GitLab 资源。通过提供 GitLab RESTful API 工具，该服务器允许 LLM 执行用户任务查询、项目搜索、合并请求管理等多种 GitLab 操作，从而实现更智能化的研发流程和知识管理。

主要功能点

GitLab RESTful API 集成: 提供对 GitLab API v4 版本的全面支持，允许 LLM 无缝访问 GitLab 的各项功能。
智能字段映射: 简化 API 使用，自动将用户友好的字段名转换为深层嵌套的 API 路径，降低使用门槛。
字段过滤系统: 支持精确控制 API 响应的数据字段，减少不必要的数据传输，提高效率。
多种操作支持: 预置了多种常用的 GitLab 操作，如获取用户任务、搜索用户和项目、管理合并请求等，开箱即用。
Smithery 兼容: 完全兼容 Smithery 部署和分发标准，方便在 Smithery 环境中安装和使用。

安装步骤

安装 Node.js 和 npm: 确保您的系统已安装 Node.js 和 npm (Node Package Manager)。
下载仓库代码: 从 GitHub 仓库 https://github.com/ZephyrDeng/gitlab-mcp-server 下载代码到本地。
安装依赖: 在仓库根目录下，打开终端并执行命令安装项目依赖：
```
npm install
```
构建项目: 执行命令构建项目，将 TypeScript 代码编译为 JavaScript 代码：
```
npm run build
```

配置环境变量: 设置以下环境变量，用于配置 GitLab API 连接信息：

GITLAB_API_URL=https://your-gitlab-instance.com  # 您的 GitLab 实例 URL，例如 https://gitlab.com 或您自建的 GitLab 地址
GITLAB_TOKEN=your_access_token                    # 您的 GitLab 个人访问令牌，需要具有访问 GitLab API 的权限

您可以通过多种方式设置环境变量，例如在 '.env' 文件中配置或直接在终端中 export。

启动服务器: 执行命令启动 MCP 服务器：
```
npm run start
```
服务器默认监听标准输入输出 (stdio)，等待 MCP 客户端连接。

服务器配置

为了使 MCP 客户端（例如 Claude 桌面客户端）能够连接到 GitLab MCP 服务器，您需要在客户端的配置文件中添加服务器配置信息。以 Claude 桌面客户端为例，您需要编辑配置文件 'claude_desktop_config.json'，该文件通常位于：

MacOS: '~/Library/Application Support/Claude/claude_desktop_config.json'
Windows: '%APPDATA%/Claude/claude_desktop_config.json'

在 'mcpServers' 字段下添加 GitLab MCP 服务器的配置，配置信息为 JSON 格式：

{
  "mcpServers": {
    "@zephyr-mcp/gitlab-restful-api": {  // 服务器名称，用于在客户端中标识和调用，建议与 npm 包名一致
      "command": "npx",                   // 启动服务器的命令，这里使用 npx
      "args": ["-y", "@zephyr-mcp/gitlab-restful-api"] // 命令参数，-y 表示自动同意执行，@zephyr-mcp/gitlab-restful-api 是要执行的 npm 包名，npx 会自动查找并执行该包
      // 注意：这里假设您已经将项目发布为 npm 包 @zephyr-mcp/gitlab-restful-api，并且可以通过 npx 直接运行。
      // 如果您是本地开发运行，可能需要调整 command 和 args 配置，例如：
      // "command": "node",
      // "args": ["dist/index.js"] // 指向编译后的服务器入口文件
    }
  }
}

配置说明:

'"@zephyr-mcp/gitlab-restful-api"': 服务器的名称，可以自定义，但建议使用与 npm 包名相同的名称，以便于管理和识别。
'"command": "npx"': 指定用于启动服务器的命令为 'npx'。'npx' 是 Node.js 的包执行器，可以方便地运行 npm 包。
'"args": ["-y", "@zephyr-mcp/gitlab-restful-api"]': 传递给 'npx' 命令的参数。
- '"-y"': 表示自动同意执行，避免在执行过程中出现需要用户确认的提示。
- '"@zephyr-mcp/gitlab-restful-api"': 指定要通过 'npx' 执行的 npm 包名称。'npx' 会在 'node_modules' 目录或 npm 仓库中查找并执行名为 '@zephyr-mcp/gitlab-restful-api' 的包。

请注意: 上述配置假设您已经将项目打包并发布为 npm 包 '@zephyr-mcp/gitlab-restful-api'。如果您是本地开发运行，尚未发布 npm 包，您可能需要将 'command' 和 'args' 配置修改为直接运行本地编译后的 JavaScript 文件，例如：

{
  "mcpServers": {
    "gitlab-mcp-server-local": { // 本地运行的服务器名称，可以自定义
      "command": "node",       // 使用 node 命令运行 JavaScript 文件
      "args": ["dist/index.js"] // 指向编译后的服务器入口文件路径，根据实际情况修改
    }
  }
}

确保 'dist/index.js' 文件存在，并且是您构建项目后生成的服务器入口文件。

基本使用方法

配置完成后，在支持 MCP 协议的 LLM 客户端中，您就可以调用 'GitlabRestfulApiTool' 工具来访问 GitLab API 了。

例如，在 Claude 中，您可以指示 Claude 使用 'Gitlab API MCP-Tool' 工具来查询 GitLab 信息，例如：

请使用 Gitlab API MCP-Tool 工具，operation 为 searchUserWithProjects，username 为 "您的 GitLab 用户名"，fields 为 ["id", "name", "username", "project_names"] 来搜索用户及其项目信息。

LLM 客户端会将上述指令转换为 MCP 请求发送给 GitLab MCP 服务器，服务器执行相应的 GitLab API 调用并将结果返回给客户端，最终由 LLM 将结果呈现给用户。

您可以参考 '工具说明' 和 '使用示例' 章节了解 'GitlabRestfulApiTool' 工具支持的各种操作和参数，以便更灵活地使用该工具。

关键词