MCP Gitlab Jira

🚀 MCP GitLab Jira 服务器

这是一个用于集成 GitLab 和 Jira 的模型上下文协议（MCP）服务器。该服务器允许像 gemini-cli 这样的 AI 代理与你的 GitLab 和 Jira 实例进行交互。

🚀 快速开始

本 MCP 服务器可助力 AI 代理与 GitLab 和 Jira 实例交互。以下将为你介绍其特性、安装、使用及开发等相关内容。

✨ 主要特性

GitLab

• 项目管理：可列出所有可访问的项目，也能按名称筛选项目。
• 合并请求操作：列出项目的合并请求，获取详细信息（包括差异比较），添加评论并分配审核人员。
• 文件获取：获取指定 SHA 版本下特定文件的内容。
• 版本发布管理：列出项目的所有版本发布，或筛选自特定版本以来的发布。
• 用户管理：列出项目成员，通过用户名获取用户 ID，并获取用户活动信息。

Jira

• 工单管理：获取工单的详细信息、评论，添加评论，使用 JQL 搜索工单，创建新工单，获取可用的转换操作，更新工单并将工单转换到新状态。

📦 安装指南

前提条件

• Node.js 18 及以上版本
• 具有 API 访问权限的 GitLab 个人访问令牌
• Jira API 令牌
• 可访问的 GitLab 实例（本地部署或 GitLab.com）
• 可访问的 Jira 实例

安装步骤

1. 全局安装软件包：

npm i -g mcp-gitlab-jira

2. 设置环境变量：

# GitLab
export GITLAB_URL="https://your-gitlab-instance.com"
export GITLAB_ACCESS_TOKEN="your-personal-access-token"

# Jira
export ATLASSIAN_SITE_NAME="your-atlassian-site-name"
export ATLASSIAN_USER_EMAIL="your-email@example.com"
export ATLASSIAN_API_TOKEN="your-jira-api-token"

3. 手动测试服务器：

# 测试服务器是否能正常启动
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | mcp-gitlab-jira

服务器应启动并在 stderr 中记录 “GitLab/Jira MCP server started”。

与 MCP 客户端配合使用

gemini-cli 或其他 MCP 客户端的配置

创建或更新你的 MCP 配置文件（通常为 ~/.mcp/config.json 或类似文件）：

{
  "mcpServers": {
    "gitlab-jira-mcp": {
      "command": "mcp-gitlab-jira",
      "env": {
        "GITLAB_URL": "https://your-gitlab-instance.com",
        "GITLAB_ACCESS_TOKEN": "your-personal-access-token",
        "ATLASSIAN_SITE_NAME": "your-atlassian-site-name",
        "ATLASSIAN_USER_EMAIL": "your-email@example.com",
        "ATLASSIAN_API_TOKEN": "your-jira-api-token"
      }
    }
  }
}

🐳 使用 Docker 运行

你也可以使用 Docker Hub 上的预构建镜像，在 Docker 容器中运行此 MCP 服务器。

可用的 Docker 镜像

Docker 镜像会为每个版本自动构建并发布到 Docker Hub：

• 最新版本：hainanzhao/mcp-gitlab-jira:latest
• 特定版本：hainanzhao/mcp-gitlab-jira:v0.1.2、hainanzhao/mcp-gitlab-jira:v0.1.1 等。
• 查看所有可用标签：Docker Hub - mcp-gitlab-jira

这些镜像支持多种架构：linux/amd64 和 linux/arm64（兼容 Apple Silicon）。

使用方法

1. 拉取并运行 Docker 容器：

docker run -d --name mcp-gitlab-jira-container \
  -e GITLAB_URL="https://your-gitlab-instance.com" \
  -e GITLAB_ACCESS_TOKEN="your-personal-access-token" \
  -e ATLASSIAN_SITE_NAME="your-atlassian-site-name" \
  -e ATLASSIAN_USER_EMAIL="your-email@example.com" \
  -e ATLASSIAN_API_TOKEN="your-jira-api-token" \
  hainanzhao/mcp-gitlab-jira:latest

2. 替代方案：无持久化容器运行（一次性执行）：

docker run --rm -i \
  -e GITLAB_URL="https://your-gitlab-instance.com" \
  -e GITLAB_ACCESS_TOKEN="your-personal-access-token" \
  -e ATLASSIAN_SITE_NAME="your-atlassian-site-name" \
  -e ATLASSIAN_USER_EMAIL="your-email@example.com" \
  -e ATLASSIAN_API_TOKEN="your-jira-api-token" \
  hainanzhao/mcp-gitlab-jira:latest

与 MCP 客户端配合使用（Docker 方式）

你可以通过以下两种方式将 Docker 容器与 MCP 客户端配合使用：

方案 1：使用持久化容器（推荐）

首先，按上述方法启动容器，然后更新你的 MCP 配置文件。由于必要的环境变量已通过 docker run 命令的 -e 标志直接传递给容器，因此 env 块为空。

{
  "mcpServers": {
    "gitlab-jira-mcp": {
      "command": "docker",
      "args": ["exec", "-i", "mcp-gitlab-jira-container", "npm", "start"],
      "env": {}
    }
  }
}

方案 2：使用一次性执行

此方法会为每个 MCP 会话运行一个新容器：

{
  "mcpServers": {
    "gitlab-jira-mcp": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GITLAB_URL=https://your-gitlab-instance.com",
        "-e", "GITLAB_ACCESS_TOKEN=your-personal-access-token",
        "-e", "ATLASSIAN_SITE_NAME=your-atlassian-site-name",
        "-e", "ATLASSIAN_USER_EMAIL=your-email@example.com",
        "-e", "ATLASSIAN_API_TOKEN=your-jira-api-token",
        "hainanzhao/mcp-gitlab-jira:latest"
      ],
      "env": {}
    }
  }
}

💻 使用示例

基础用法

以下是使用 MCP 服务器与 GitLab 和 Jira 交互的示例：

# 测试服务器启动
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | mcp-gitlab-jira

高级用法

使用 Docker 运行

# 拉取并运行 Docker 容器
docker run -d --name mcp-gitlab-jira-container \
  -e GITLAB_URL="https://your-gitlab-instance.com" \
  -e GITLAB_ACCESS_TOKEN="your-personal-access-token" \
  -e ATLASSIAN_SITE_NAME="your-atlassian-site-name" \
  -e ATLASSIAN_USER_EMAIL="your-email@example.com" \
  -e ATLASSIAN_API_TOKEN="your-jira-api-token" \
  hainanzhao/mcp-gitlab-jira:latest

📚 详细文档

可用工具

GitLab 工具

• gitlab_get_merge_request_details：获取 GitLab 合并请求的详细信息，包括文件差异比较。
• gitlab_get_file_content：获取 GitLab 项目中指定 SHA 版本下特定文件的内容。
• gitlab_add_comment_to_merge_request：向 GitLab 合并请求添加评论。可以是普通评论、对现有讨论的回复或特定行的内联评论。
• gitlab_list_merge_requests：列出给定 GitLab 项目的合并请求。
• gitlab_assign_reviewers_to_merge_request：为 GitLab 合并请求分配审核人员。
• gitlab_list_project_members：列出给定 GitLab 项目的所有成员（贡献者）。
• gitlab_list_project_members_by_project_name：按项目名称列出给定 GitLab 项目的所有成员（贡献者）。
• gitlab_list_projects_by_name：使用模糊、不区分大小写的匹配方式按名称筛选 GitLab 项目。
• gitlab_list_all_projects：列出所有可访问的 GitLab 项目。
• gitlab_list_all_releases：获取给定 GitLab 项目的版本发布信息。
• gitlab_list_releases_since_version：筛选自特定版本以来给定 GitLab 项目的版本发布。
• gitlab_get_user_id_by_username：根据用户名获取 GitLab 用户 ID。
• gitlab_get_user_activities：根据用户名获取给定 GitLab 用户的活动信息，可选择按日期筛选。

Jira 工具

• jira_get_jira_ticket_details：获取 Jira 工单的详细信息。
• jira_get_jira_ticket_comments：获取 Jira 工单的评论。
• jira_add_comment_to_ticket：向 Jira 工单添加评论。
• jira_search_tickets_by_jql：使用 JQL（Jira 查询语言）字符串搜索 Jira 工单。
• jira_create_ticket：使用给定字段创建新的 Jira 工单。
• jira_get_available_transitions：获取 Jira 工单的可用转换操作。
• jira_update_ticket：更新 Jira 工单的摘要、描述和标签。
• jira_update_custom_fields：更新 Jira 工单的自定义字段。
• jira_transition_ticket：将 Jira 工单转换到新状态。

故障排除

常见问题

1. “Cannot find module” 错误：如果你在本地开发，请确保已运行 npm install 和 npm run build。
2. 认证错误：验证你的 GITLAB_ACCESS_TOKEN、ATLASSIAN_USER_EMAIL 和 ATLASSIAN_API_TOKEN 是否具有必要的权限。
3. 连接错误：确保你的 GITLAB_URL 和 ATLASSIAN_SITE_NAME 正确且可访问。
4. 服务器无响应：检查 MCP 服务器进程是否正在运行，以及配置文件中的路径是否正确。

调试模式

若要查看详细日志，可直接运行服务器：

export GITLAB_URL="your-url"
export GITLAB_ACCESS_TOKEN="your-token"
export ATLASSIAN_SITE_NAME="your-atlassian-site-name"
export ATLASSIAN_USER_EMAIL="your-email@example.com"
export ATLASSIAN_API_TOKEN="your-jira-api-token"
mcp-gitlab-jira

开发相关

本地开发

若要进行开发，请克隆仓库并安装依赖：

npm install
npm run build

本地 Docker 开发

在推送之前，可在本地测试 Docker 构建：

# 在本地构建并测试 Docker 镜像
./scripts/build-docker-local.sh

此脚本将构建 Docker 镜像并运行基本测试，以确保其正常工作。

维护人员注意：有关设置自动化 Docker Hub 发布的信息，请参阅 Docker 设置指南。

项目结构

• src/index.ts：主 MCP 服务器实现
• src/gitlab.service.ts：GitLab API 客户端
• src/gitlab.ts：GitLab 类型定义
• src/jira.service.ts：Jira API 客户端
• src/jira.ts：Jira 类型定义
• dist/：编译后的 JavaScript 输出

添加新功能

1. 向 GitLabService 或 JiraService 类添加新方法。
2. 在 index.ts 的 allTools 数组中定义新工具。
3. 在 index.ts 的工具处理程序中添加相应的 case 语句。
4. 使用 npm run build 重新构建项目。

🔧 技术细节

本项目使用 Node.js 实现 MCP 服务器，通过 src/gitlab.service.ts 和 src/jira.service.ts 分别与 GitLab 和 Jira 的 API 进行交互。项目使用 TypeScript 编写，在 src 目录下定义类型和服务，编译后的 JavaScript 文件输出到 dist 目录。通过 npm run build 命令将 TypeScript 代码编译为 JavaScript 代码。

📄 许可证

本项目采用 ISC 许可证。