JIRA MCP Integration

Name: JIRA MCP Integration
Author: MankowskiNick

本地服务

github.com/MankowskiNick版本控制738 周前更新

代码仓库

关于 JIRA MCP Integration

JIRA MCP Integration 是面向项目和测试管理的 MCP 服务，让 AI 助手通过标准协议操作 JIRA，并可连接 Zephyr 管理测试步骤。它支持创建、查询、更新和关联工单。

主要功能

01创建和检索 JIRA 工单
02按 JQL 条件搜索工单
03更新工单字段并建立关联
04为故事工单自动创建测试工单
05读取和添加 Zephyr 测试步骤

适用场景

01在对话中创建项目工单
02按类型和条件查找工单
03为故事关联测试工单
04维护 Zephyr 测试步骤

MCP 相关

该 MCP 服务向 MCP 客户端提供 JIRA 工单管理工具，并通过 Zephyr 集成读取和添加测试步骤。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

暂未收录安装方式

我们还没有获取到这个服务的安装包或远程地址，请按项目 README 中的说明安装。

代码仓库

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

JIRA MCP 集成

一个用于将 JIRA 与 Claude 集成的 Model Context Protocol 服务。此工具允许 Claude 在对话中直接创建 JIRA 工单。

概述

JIRA MCP 项目是一个 Node.js/TypeScript 应用程序，提供用于与 JIRA 和 Zephyr 集成的 Model Context Protocol（MCP）服务。它允许 AI 助手通过标准化协议与 JIRA 交互以进行项目管理，并与 Zephyr 交互以进行测试管理。

功能

创建 JIRA 工单，填写摘要、描述、验收标准和问题类型
使用灵活的 JQL 查询或按问题类型搜索 JIRA 工单
为 Story 工单分配故事点
自动为带有故事点的 Story 创建关联的 Test 工单
增强错误处理，针对自定义字段验证问题自动重试
更新为使用最新的 JIRA REST API v3 规范（符合 CHANGE-2046）
按问题类型和其他条件搜索 JIRA 工单
使用新的字段值更新现有 JIRA 工单
按指定的关系类型关联 JIRA 工单
获取并添加 Zephyr 测试工单的测试步骤
与 Claude 桌面应用无缝集成
使用 Claude 桌面配置文件进行简单配置

安装

克隆代码仓库：

git clone https://github.com/MankowskiNick/jira-mcp.git
cd jira-mcp

安装依赖项：
```
npm install
```

构建项目：

 npm run build -- on unix systems
 -- or --
 npm run build-win -- on windows systems

配置

配置位置

将 JIRA MCP 服务配置添加到 Claude 配置文件中：

Claude 桌面应用：
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Windows：%APPDATA%\Roaming\Claude\claude_desktop_config.json
- Linux：~/.config/Claude/claude_desktop_config.json
VSCode 扩展：
- ~/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

配置模板

已在 jira-mcp-config-template.json 中提供配置文件模板。此模板展示了 JIRA MCP 服务的所有可用配置选项。

基本配置

将以下配置添加到 Claude 配置文件中：

{
  "mcpServers": {
    "jira-mcp": {
      "command": "node",
      "args": ["/path/to/project/build/index.js"],
      "env": {
        "JIRA_HOST": "your-site.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_PROJECT_KEY": "your_project_key",
        "AUTO_CREATE_TEST_TICKETS": "true",

        "JIRA_ACCEPTANCE_CRITERIA_FIELD": "customfield_10429",
        "JIRA_STORY_POINTS_FIELD": "customfield_10040",
        "JIRA_EPIC_LINK_FIELD": "customfield_10014",

        "JIRA_PRODUCT_FIELD": "customfield_10757",
        "JIRA_PRODUCT_VALUE": "Your Product Name",
        "JIRA_PRODUCT_ID": "12345",

        "JIRA_CATEGORY_FIELD": "customfield_10636",
        "USE_ALTERNATE_CATEGORY": "false",
        "JIRA_DEFAULT_CATEGORY_VALUE": "Default Category",
        "JIRA_DEFAULT_CATEGORY_ID": "12345",
        "JIRA_ALTERNATE_CATEGORY_VALUE": "Alternate Category",
        "JIRA_ALTERNATE_CATEGORY_ID": "67890"
      }
    }
  }
}

必需配置

以下环境变量是 JIRA MCP 服务正常运行所必需的：

JIRA_HOST：JIRA 实例域名（例如，company.atlassian.net）
JIRA_USERNAME：JIRA 用户名（通常是电子邮件地址）
JIRA_API_TOKEN：JIRA API 令牌（获取方法见下文）
JIRA_PROJECT_KEY：JIRA 项目的键（例如，SCRUM、DEV 等）

可选配置

创建测试工单

AUTO_CREATE_TEST_TICKETS：设为 "true"（默认值）可自动为带有点数的 Story 工单创建关联的 Test 工单，设为 "false" 可禁用此功能

Zephyr 集成

Zephyr 集成需要以下环境变量，才能向测试工单添加测试步骤：

ZAPI_BASE_URL：Zephyr API 的基础 URL（默认值："https://prod-api.zephyr4jiracloud.com/connect"）
ZAPI_ACCESS_KEY：Zephyr 访问密钥（可在 Zephyr Cloud 设置中的 API Keys 下找到）
ZAPI_SECRET_KEY：Zephyr 秘密密钥（可在 Zephyr Cloud 设置中的 API Keys 下找到）
ZAPI_JWT_EXPIRE_SEC：JWT 令牌过期时间，以秒为单位（默认值：3600）

自定义字段配置

以下环境变量允许你配置自定义字段，无需在源代码中硬编码：

JIRA_ACCEPTANCE_CRITERIA_FIELD：验收标准的字段 ID（默认值："customfield_10429"）
JIRA_STORY_POINTS_FIELD：故事点数的字段 ID（默认值："customfield_10040"）
JIRA_EPIC_LINK_FIELD：史诗链接的字段 ID（默认值："customfield_10014"）

产品字段配置（可选）

此配置完全可选。要使用此功能，必须同时提供以下三个变量：

JIRA_PRODUCT_FIELD：产品字段的字段 ID
JIRA_PRODUCT_VALUE：产品的显示值
JIRA_PRODUCT_ID：产品选项的 ID

类别字段配置（可选）

此配置完全可选。仅当指定 JIRA_CATEGORY_FIELD 时才会使用类别字段：

JIRA_CATEGORY_FIELD：类别字段的字段 ID
USE_ALTERNATE_CATEGORY：设为 "true" 使用备用类别，设为 "false" 使用默认类别
JIRA_DEFAULT_CATEGORY_VALUE：默认类别的显示值
JIRA_DEFAULT_CATEGORY_ID：默认类别选项的 ID
JIRA_ALTERNATE_CATEGORY_VALUE：备用类别的显示值
JIRA_ALTERNATE_CATEGORY_ID：备用类别选项的 ID

危机字段配置（可选）

JIRA_CRISIS_FIELD：危机字段的字段 ID（默认值："customfield_10597"）
JIRA_CRISIS_YES_ID："Yes" 选项的 ID（默认值："18258"）
JIRA_CRISIS_NO_ID："No" 选项的 ID（默认值："18259"）

最简配置示例

如果你需要最简配置，可以使用：

{
  "mcpServers": {
    "jira-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/jira-mcp/build/index.js"],
      "env": {
        "JIRA_HOST": "your-site.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_PROJECT_KEY": "your_project_key"
      }
    }
  }
}

查找自定义字段 ID

如果需要查找 JIRA 实例的自定义字段 ID：

在 JIRA 实例中打开一个工单
按 F12 打开开发者工具
转到 Network 选项卡
刷新页面
查找对 issue/[ISSUE-KEY] 的请求
检查响应，找到自定义字段 ID

或者，你可以使用 JIRA API 获取所有字段的列表：

GET https://your-site.atlassian.net/rest/api/3/field

可用工具

create-ticket

创建新的 JIRA 工单。

参数：

summary：工单的标题／摘要（必填）
issue_type：问题类型（Bug、Task、Story 或 Test，默认为 Task）
description：工单的详细描述（可选）
acceptance_criteria：工单的验收标准（可选，存储在 customfield_10429 中）
story_points：工单的故事点数（可选，采用斐波那契数列：1、2、3、5、8、13 等）
create_test_ticket：覆盖自动创建关联 Test 工单的默认设置（可选，布尔值）
parent_epic：要关联此工单的父级史诗工单的键（可选，例如 “PROJ-123”）
sprint：要将工单分配到的迭代名称（可选，例如 “2025_C1_S07”）
story_readiness：故事是否已准备好进入开发阶段（可选，“Yes” 或 “No”）
crisis：此工单是否代表危机／紧急问题（可选，“Yes” 或 “No”）

创建带有故事点数的 Story 工单时：

系统会自动为 Story 添加 “QA-Testable” 标签
系统会自动创建关联的 Test 工单（如果启用了 AUTO_CREATE_TEST_TICKETS）
Test 工单使用 Story 的标题作为其描述
Test 工单通过 “Test Case Linking” 关系与 Story 关联

示例：

{
  "summary": "Implement user authentication feature",
  "issue_type": "Story",
  "description": "As a user, I want to be able to log in to the application",
  "acceptance_criteria": "- Users can log in with email and password\n- Password reset functionality works via email",
  "story_points": 5,
  "parent_epic": "PROJ-100",
  "sprint": "2025_C1_S07",
  "story_readiness": "Yes"
}

get-ticket

检索现有 JIRA 工单的详细信息。

参数：

ticket_id：要读取的 JIRA 工单的 ID／键（必填，例如 “PROJ-123”）

示例：

{
  "ticket_id": "PROJ-123"
}

响应包含工单的所有字段，包括自定义字段。

search-tickets

按问题类型和其他条件搜索 JIRA 工单。

参数：

issue_type：要搜索的问题类型（Bug、Task、Story 或 Test）（必填）
max_results：返回结果的最大数量（可选，默认值：10，最大值：50）
additional_criteria：要纳入搜索的其他 JQL 条件（可选）

示例：

{
  "issue_type": "Bug",
  "max_results": 20,
  "additional_criteria": "status = 'Open' AND priority = 'High'"
}

此工具可查找 JIRA 项目中指定类型的所有工单。你还可以提供其他 JQL 条件，进一步缩小搜索范围。

update-ticket

使用新的字段值更新现有 JIRA 工单。

参数：

ticket_key：要更新的 JIRA 工单的键（必填，例如 “PROJ-123”）
sprint：要将工单分配到的迭代名称（可选，例如 “2025_C1_S07”）
story_readiness：故事是否已准备好进入开发阶段（可选，“Yes” 或 “No”）

示例：

{
  "ticket_key": "PROJ-123",
  "sprint": "2025_C1_S07",
  "story_readiness": "Yes"
}

此工具可更新现有工单的迭代信息和故事就绪状态。必须至少提供一个字段才能执行更新。

link-tickets

使用指定的关系类型关联两个 JIRA 工单。

参数：

outward_issue：外向问题的键（必填，例如 “PROJ-123”）
inward_issue：内向问题的键（必填，例如 “PROJ-456”）
link_type：要创建的关联类型（可选，默认为 “Test Case Linking”）

示例：

{
  "outward_issue": "PROJ-123",
  "inward_issue": "PROJ-456",
  "link_type": "Blocks"
}

此工具会按照指定的关系类型关联两个工单。例如，“PROJ-123 blocks PROJ-456”。

get-test-steps

从 Zephyr 测试工单中检索测试步骤。

参数：

ticket_key：要从中检索步骤的测试工单的键（必填，例如 “PROJ-123”）

示例：

{
  "ticket_key": "PROJ-123"
}

此工具可检索 Zephyr 测试工单关联的所有测试步骤。响应包含每个步骤的描述、测试数据和预期结果。

add-test-steps

通过 Zephyr 集成为测试工单添加测试步骤。

参数：

ticket_key：要添加步骤的测试工单键（必填，例如："PROJ-123"）
steps：测试步骤对象数组（必填），每个步骤对象包含：
- step：测试步骤说明（必填）
- data：步骤的测试数据（可选）
- result：步骤的预期结果（可选）

示例：

{
  "ticket_key": "PROJ-123",
  "steps": [
    {
      "step": "Navigate to the login page",
      "data": "https://example.com/login",
      "result": "Login form is displayed"
    },
    {
      "step": "Enter valid credentials",
      "data": "username=test, password=password123",
      "result": "User is logged in successfully"
    }
  ]
}

此工具需要安装并配置 Zephyr for Jira Cloud。你需要在配置文件中设置 Zephyr API 环境变量。

项目架构

项目采用模块化架构，职责划分清晰：

jira-mcp/
├── src/                      # Source code
│   ├── index.ts              # Main entry point
│   ├── utils.ts              # Shared utility functions
│   ├── jira/                 # JIRA integration module
│   │   ├── api.ts            # JIRA API interaction functions
│   │   ├── formatting.ts     # JIRA content formatting utilities
│   │   ├── index.ts          # JIRA module exports
│   │   ├── tools.ts          # JIRA MCP tools registration
│   │   └── types.ts          # JIRA type definitions
│   └── zephyr/               # Zephyr integration module
│       ├── auth.ts           # Zephyr authentication utilities
│       ├── index.ts          # Zephyr module exports
│       ├── test-steps.ts     # Zephyr test steps API functions
│       ├── tools.ts          # Zephyr MCP tools registration
│       └── types.ts          # Zephyr type definitions
├── util/                     # Utility scripts
│   └── update-mcp-settings.js # Script to update MCP settings
├── package.json              # Project metadata and dependencies
└── tsconfig.json             # TypeScript configuration

核心组件

MCP 服务

应用使用 @modelcontextprotocol/sdk 软件包创建 MCP 服务。此服务提供可供 AI 助手使用的工具，以便与 JIRA 和 Zephyr 交互。

// src/index.ts
const server = new McpServer({
  name: "jira-mcp",
  version: "1.0.0",
});

// Register tools
registerJiraTools(server);
registerZephyrTools(server);

// Connect using stdio transport
const transport = new StdioServerTransport();
await server.connect(transport);

search-tickets-jql

使用自定义 JQL（JIRA 查询语言）查询搜索 JIRA 工单。

参数：

jql：要执行的 JQL 查询（必填）——任何有效的 JIRA 查询语言表达式
max_results：要返回的最大结果数（可选，默认值：10，最大值：50）

示例：

搜索特定工单：key = "PROJ-123"
按项目和状态搜索：project = "MYPROJECT" AND status = "In Progress"
按经办人搜索：assignee = "[email protected]"
按多个条件搜索：project = "PROJ" AND issuetype = "Bug" AND priority = "High"

此工具可使用任何有效的 JQL 查询灵活搜索 JIRA 工单。它使用更新后的 /rest/api/3/search/jql 端点，以便与当前的 JIRA Cloud 实例实现最佳兼容。

JIRA 集成

JIRA 集成模块提供用于与 JIRA REST API 交互的工具：

create-ticket：创建包含可自定义字段的新 JIRA 工单
link-tickets：按指定关系关联两个 JIRA 工单
get-ticket：获取特定 JIRA 工单的信息
search-tickets：使用 JQL（JIRA 查询语言）搜索 JIRA 工单
update-ticket：更新现有 JIRA 工单的信息

该模块使用 JIRA API 的 Basic Authentication，并按照 JIRA 的 Atlassian 文档格式（ADF）整理内容。

Zephyr 集成

Zephyr 集成模块提供用于管理 Zephyr 测试步骤的工具：

get-test-steps：获取特定测试工单的测试步骤
add-test-steps：为测试工单添加测试步骤

该模块使用 Zephyr API 的 JWT 身份验证，为每个请求生成签名令牌。

身份验证

JIRA 身份验证

JIRA 使用用户名和 API 令牌进行 Basic Auth 身份验证：

const auth = Buffer.from(
  `${process.env.JIRA_USERNAME}:${process.env.JIRA_API_TOKEN}`
).toString("base64");

Zephyr 身份验证

Zephyr 使用通过特定算法生成的 JWT 令牌进行身份验证：

// Generate JWT for Zephyr API
const jwtToken = generateZephyrJwt("GET", apiPath, queryParams);

JWT 生成过程包括：

根据请求方法、路径和查询参数创建规范字符串
为该字符串生成 SHA-256 哈希值
创建包含哈希值、账户 ID 和时间戳等声明的 JWT
使用 Zephyr Secret Key 通过 HMAC-SHA256 对 JWT 进行签名

数据格式化

项目包含用于按 JIRA 要求格式化数据的实用工具：

formatDescription：格式化 JIRA 工单描述文本
formatAcceptanceCriteria：使用适当的项目符号格式化验收标准

这些实用工具会创建符合 JIRA 的 Atlassian 文档格式（ADF）的 JSON 结构。

错误处理

应用在各处都包含全面的错误处理：

检查 API 响应的成功状态码
如果 API 响应中包含错误消息，则提取这些消息
捕获并记录异常
以统一格式向客户端返回错误信息

实用脚本

项目在 util 目录中包含实用脚本，可帮助完成配置和设置任务。

update-mcp-settings.js

此脚本可自动将 JIRA MCP 配置更新到 Claude VSCode 扩展的 MCP 设置中。

用途：

从 util 目录读取合并后的 JIRA MCP 配置文件
使用 JIRA MCP 配置更新 Claude VSCode 扩展的 MCP 设置文件
处理并修复设置文件中可能出现的 JSON 解析问题
简化 VSCode 扩展用户的配置流程

用法：

node util/update-mcp-settings.js

适用场景：

更改 JIRA MCP 配置后
设置 JIRA MCP 与 Claude VSCode 扩展的集成时
遇到 VSCode 扩展 MCP 设置问题时

此脚本需要 util 目录中有一个名为 merged-jira-mcp-config.json 的文件，其中应包含完整的 JIRA MCP 配置。随后，脚本会更新位于 /home/joe/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json 的 VSCode 扩展设置文件。

注意： 如果你的文件路径与默认路径不同，可能需要修改脚本以匹配你的具体路径。

与 Claude 搭配使用

正确配置后，你可以直接让 Claude 创建 JIRA 工单：

Please create a JIRA ticket to track the database performance issue we discussed.

你也可以为工单指定验收标准：

Create a JIRA ticket for implementing the new user authentication feature with the following acceptance criteria:
- Users can log in with email and password
- Password reset functionality works via email
- Account lockout occurs after 5 failed attempts
- OAuth integration with Google and Facebook

Claude 将使用 create-ticket 工具，在你的 JIRA 项目中创建包含所有指定详细信息的工单。

API 更新与兼容性

此 JIRA MCP 已更新为使用最新的 JIRA REST API v3 规范，以确保持续兼容 Atlassian 不断演进的平台。

主要更新

搜索端点迁移：从已弃用的 /rest/api/3/search 更新为 /rest/api/3/search/jql（符合 CHANGE-2046）
增强错误处理：针对自定义字段验证错误自动重试；如果自定义字段值变为无效，系统会自动在不包含问题字段的情况下重试创建工单
改进分页支持：响应处理支持旧版（startAt、maxResults、total）和新版（isLast、nextPageToken）分页格式
面向未来的架构：已验证所有端点均使用当前的 JIRA REST API v3 路径

弃用时间表

2025 年 8 月 1 日：旧搜索端点将逐步关闭
2025 年 10 月 31 日：所有发往已弃用端点的流量都将被拦截

此 MCP 已为这些变更做好充分准备，在过渡期间及之后都将继续顺畅运行。

获取 JIRA API 令牌

登录你的 Atlassian 账户：https://id.atlassian.com/manage-profile/security
前往 Security > API tokens
点击“Create API token”
为令牌命名（例如，“Claude Integration”）
点击“Create”
复制令牌（之后将无法再次查看）

故障排除

如果遇到问题：

检查 JIRA 凭据是否正确
确认配置中项目 index.js 文件的路径
确保已授予 Claude 使用工具的权限
检查 Claude 的控制台日志中是否有与 JIRA MCP 服务相关的错误消息

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

JIRA MCP Integration

关于 JIRA MCP Integration

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

JIRA MCP 集成

概述

目录

功能

安装

配置

配置位置

配置模板

基本配置

必需配置

可选配置

创建测试工单

Zephyr 集成

自定义字段配置

产品字段配置（可选）

类别字段配置（可选）

危机字段配置（可选）

最简配置示例

查找自定义字段 ID

可用工具

create-ticket

get-ticket

search-tickets

update-ticket

link-tickets

get-test-steps

add-test-steps

项目架构

核心组件

MCP 服务

search-tickets-jql

JIRA 集成

Zephyr 集成

身份验证

JIRA 身份验证

Zephyr 身份验证

数据格式化

错误处理

实用脚本

update-mcp-settings.js

与 Claude 搭配使用

API 更新与兼容性

主要更新

弃用时间表

获取 JIRA API 令牌

故障排除

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？