GitLab MCP Server (noqta-gitlab-server)

GitLab MCP 服务（noqta-gitlab-server）

一个用于与 GitLab API 交互的模型上下文协议（MCP）服务。

此服务允许 AI 助手（例如通过 MCP 集成使用 Claude）直接通过自然语言命令在 GitLab 上执行各种操作，例如搜索代码库、管理议题、创建分支等。

功能 / 可用工具

此服务向 MCP 客户端公开以下工具：

• search_repositories：按名称搜索 GitLab 项目。
• get_project_from_git_url：根据 git 远程 URL 获取 GitLab 项目详情。
• list_issues：列出特定 GitLab 项目的议题（可按状态、标签、指派人和范围筛选）。
• get_my_issues：列出已认证用户在所有项目中被指派或创建的议题（可按状态和范围筛选）。
• get_issue：根据 IID 获取项目中特定议题的详情。
• create_issue_note：向特定议题添加评论（备注）。
• update_issue：更新议题属性（例如标题、描述、标签、状态）。
• bulk_update_issues：一次性更新项目中多个议题的属性。
• create_branch：从指定引用在项目中创建新分支。
• create_issue：在项目中创建新议题。
• list_documentation_wiki_pages：列出已配置文档项目的文档 Wiki 页面。
• get_documentation_wiki_page：根据 slug 获取已配置文档项目的文档 Wiki 页面。
• list_wiki_pages：列出特定 GitLab 项目的 Wiki 页面（默认使用 DOC_WIKI_PROJECT_PATH）。
• create_merge_request：创建新的合并请求。
• list_issue_notes：列出特定议题的评论（备注）。
• create_merge_request_note：向特定合并请求添加评论（备注）。
• search_user：按电子邮件或用户名搜索 GitLab 用户。
• create_repository：在用户或群组命名空间下创建新的 GitLab 项目（代码库）。

（有关每个工具的详细输入架构，请参阅服务的 ListTools 响应或源代码（src/index.ts）。）

前置条件

• Node.js（建议使用 LTS 版本）
• npm（通常随 Node.js 一起安装）
• GitLab 账户（gitlab.com 或可自托管实例）
• 具有 api 和 read_api 范围的 GitLab 个人访问令牌。

安装与设置

1. 克隆代码库：

   git clone https://github.com/nooqta/noqta-gitlab-server.git # Replace with actual URL after creation
   cd noqta-gitlab-server
   

2. 安装依赖项：

   npm install
   

3. 配置环境变量：

   • 复制示例环境文件：

     cp .env.example .env
     

   • 编辑 .env 文件：
     • 生成 GitLab 个人访问令牌：前往 GitLab 个人资料 -> Settings -> Access Tokens。创建一个具有 api 和 read_api 范围的令牌。
     • 将生成的令牌粘贴到 .env 中的 GITLAB_PERSONAL_ACCESS_TOKEN 变量。
     • （可选） 如果使用可自托管的 GitLab 实例，请将 GITLAB_API_URL 更新为指向该实例的 API 端点（例如，https://gitlab.yourcompany.com/api/v4）。否则，保留 gitlab.com 的默认值。
     • （可选） 将 DOC_WIKI_HOME_URL 设置为 Wiki 主页 URL。如果未设置 DOC_WIKI_PROJECT_PATH，系统会根据此 URL 推导其值。

4. 构建服务：

   npm run build
   

   这会将 TypeScript 代码编译为 JavaScript，并输出到 build/ 目录。

运行服务

直接使用 Node.js 运行（克隆并构建后）

如果已克隆代码库并构建项目（npm run build），可以直接运行服务：

node build/index.js

使用 npx（发布到 npm 后）

将软件包发布到 npm（名称为 @nooqta/gitlab-mcp-server）后，你可以直接使用 npx 运行，无需克隆或手动安装。npx 会下载并执行该软件包。

npx @nooqta/gitlab-mcp-server

注意： 使用 npx 运行时，服务器仍需要在执行 npx 命令的环境中设置环境变量（GITLAB_PERSONAL_ACCESS_TOKEN 和可选的 GITLAB_API_URL），或者在运行 npx 的目录中通过 .env 文件提供这些变量。

服务器通过标准输入/输出（stdio）进行通信。如需持续运行，可考虑使用 pm2 或 systemd 等进程管理器。

集成（示例：Claude Desktop）

要将此服务器与 Claude Desktop 等 MCP 客户端搭配使用，请将其配置添加到客户端的设置文件中。

配置文件位置：

• MacOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%/Claude/claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

claude_desktop_config.json 配置示例（使用 npx）：

{
  "mcpServers": {
    "@nooqta/gitlab-mcp-server": {
      "command": "npx",
      "args": ["-y", "@nooqta/gitlab-mcp-server"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "...",
        "GITLAB_API_URL": "..."
      }
    }
  }
  // Potentially other configurations...
}

claude_desktop_config.json 配置示例（使用本地构建）：

{
  "mcpServers": {
    "@nooqta/gitlab-mcp-server": {
      // Use the package name for consistency, even if running locally
      "command": "/full/path/to/your/custom-gitlab-server/build/index.js",
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "...",
        "GITLAB_API_URL": "..."
      }
    }
    // Potentially other configurations...
  }
}

重要安全提示： 此服务器使用 dotenv 从 .env 文件加载 GITLAB_PERSONAL_ACCESS_TOKEN 和 GITLAB_API_URL。切勿使用 env 属性将实际令牌或敏感 URL 直接写入 MCP 客户端配置文件（例如 claude_desktop_config.json）。请始终使用 .env 文件（本地运行时放在服务器项目目录中，或放在执行 npx 的目录中），或者通过操作系统环境提供这些变量。

开发

• 构建： npm run build（编译 TypeScript 并设置可执行权限）
• 监视模式： npm run watch（文件更改时自动重新编译）

调试

由于 MCP 服务通过 stdio 通信，直接调试可能比较棘手。使用 MCP Inspector 可以更轻松地进行调试：

npm run inspector

此命令会在 Inspector 的监控下启动服务器。在浏览器中打开控制台输出提供的 URL，即可查看 MCP 消息和服务器日志。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 文件了解相关指南。