Mcp Gitlab Jira

Mcp Gitlab Jira

开发 TypeScript

🚀 MCP GitLab Jira Server

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

🚀 快速开始

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

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

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

✨ 主要特性

GitLab

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

Jira

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

📦 安装指南

前置条件

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

安装步骤

  1. 全局安装包：
npm i -g mcp-gitlab-jira
  1. 设置环境变量：
# 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"
  1. 手动测试服务器：
# 测试服务器是否能正常启动
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
  1. 可选：无持久化容器运行（一次性执行）：
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 输出。

添加新功能

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

本地 Docker 开发

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

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

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

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

📄 许可证

本项目采用 ISC 许可证。

🔧 故障排除

常见问题

  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
默认排序 时间排序

0 个评论

« 上一篇
Github Action Trigger Mcp
下一篇 »
GitHub Project Manager
  • 0 关注
  • 0 收藏，18 浏览
  • system 提出于 2025-09-27 10:45

相似服务问题

相关AI产品

  • 暂无相关AI产品

热议话题 »