mcp-gitlab-jira - 集成GitLab与Jira，提供项目管理等功能的MCP服务器AI代理接口

探索

MCP Gitlab Jira

GitLab和Jira集成MCP服务器，提供项目管理、合并请求、问题跟踪等功能的AI代理交互接口

开发者工具版本控制 #项目管理 #代码协作 #问题跟踪 #AI集成 .TypeScript

评分 : 2.5分

下载量 : 0

更新时间 : 2025-09-03

打开站点

什么是GitLab Jira MCP Server?

这是一个智能连接器服务器，专门为开发团队设计，能够将GitLab代码管理平台和Jira项目追踪系统无缝连接。通过AI助手，您可以查询项目信息、管理合并请求、跟踪任务状态，实现自动化协作。

如何使用GitLab Jira MCP Server?

只需配置好您的GitLab和Jira账户信息，AI助手就能帮您执行各种操作，比如查看代码变更、添加代码评论、创建Jira任务、更新任务状态等，完全通过自然语言指令完成。

适用场景

适合软件开发团队、项目经理、质量保证工程师，以及任何需要同时在代码管理和项目追踪平台协作的团队成员，特别适合需要频繁在GitLab和Jira之间切换工作的场景。

主要功能

GitLab项目管理

浏览所有可访问的GitLab项目，按名称筛选项目，快速找到您需要的代码库。

合并请求管理

查看合并请求详情（包括代码差异）、添加评论、分配评审人员，全面管理代码审查流程。

文件内容查看

获取特定版本的文件内容，方便查看历史代码或比较不同版本的变更。

版本发布管理

查看项目的所有发布版本，按版本号筛选，跟踪发布历史。

Jira任务管理

获取任务详情、查看评论、添加评论、搜索任务、创建新任务，全面管理项目任务。

任务状态流转

查看可用状态转换、更新任务信息、改变任务状态，推动任务流程前进。

用户管理

查看项目成员、获取用户ID、查询用户活动，方便团队协作和权限管理。

跨平台协作

在GitLab和Jira之间无缝切换，实现代码开发与项目管理的完美结合。

优势

自动化协作：通过AI指令自动完成重复性操作，提高工作效率

无缝集成：深度整合GitLab和Jira，消除平台切换的麻烦

自然语言操作：使用简单指令即可执行复杂操作，降低使用门槛

全面覆盖：支持GitLab和Jira的大部分常用功能

多架构支持：支持Linux和Apple Silicon设备，兼容性好

局限性

需要API权限：需要预先配置GitLab和Jira的API访问令牌

网络依赖：需要稳定的网络连接访问GitLab和Jira实例

功能限制：某些高级功能可能受API限制无法完全实现

学习曲线：需要熟悉基本的GitLab和Jira概念才能有效使用

如何使用

安装服务器

通过npm全局安装MCP服务器包

配置环境变量

设置GitLab和Jira的访问凭证和环境信息

配置MCP客户端

在您的AI助手客户端中添加服务器配置

开始使用

启动AI助手，开始使用自然语言指令管理GitLab和Jira

使用案例

代码审查助手

AI帮助您审查代码合并请求，查看代码差异并提出改进建议

任务状态更新

自动更新Jira任务状态并添加进度评论

跨平台协作

根据GitLab的合并请求自动创建对应的Jira任务

版本发布跟踪

查看项目的版本发布历史和变更内容

常见问题

需要什么样的权限才能使用这个服务器？

支持自托管的GitLab和Jira实例吗？

如果遇到连接错误怎么办？

支持哪些MCP客户端？

Docker容器如何更新到新版本？

🚀 MCP GitLab Jira Server

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

🚀 快速开始

本 MCP 服务器可帮助 AI 代理与 GitLab 和 Jira 实例交互。以下是快速开始使用它的步骤：

确保满足所有前置条件。
完成安装步骤，包括全局安装包和设置环境变量。
手动测试服务器是否能正常启动。
配置 MCP 客户端以使用该服务器。

如果你想使用 Docker 运行服务器，可按照 Docker 相关部分的步骤操作。

✨ 主要特性

GitLab

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

Jira

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

📦 安装指南

前置条件

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

安装步骤

全局安装包：

npm i -g mcp-gitlab-jira

设置环境变量：

# 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"

手动测试服务器：

# 测试服务器是否能正常启动
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）。

使用方法

拉取并运行 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

可选：无持久化容器运行（一次性执行）：

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": {}
    }
  }
}

💻 使用示例

基础用法

以下是手动测试服务器启动的示例：

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | mcp-gitlab-jira

高级用法

使用 Docker 持久化容器与 MCP 客户端配合使用

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

使用 Docker 一次性执行与 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": {}
    }
  }
}

📚 详细文档

可用工具

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 工单转换到新状态。

🔧 技术细节

项目结构

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 输出。

添加新功能

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

本地 Docker 开发

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

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

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

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

📄 许可证

本项目采用 ISC 许可证。

🔧 故障排除

常见问题

“Cannot find module” 错误：如果你在本地开发，请确保已运行 npm install 和 npm run build。
身份验证错误：验证你的 GITLAB_ACCESS_TOKEN、ATLASSIAN_USER_EMAIL 和 ATLASSIAN_API_TOKEN 是否具有必要的权限。
连接错误：确保你的 GITLAB_URL 和 ATLASSIAN_SITE_NAME 正确且可访问。
服务器无响应：检查 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