使用说明

JIRA MCP集成

A. 模型上下文协议用于将JIRA与Claude集成的服务器。此工具允许Claude直接在您的对话中创建JIRA票证。

概述

JIRA MCP项目是一个Node.js/TypeScript应用程序，它提供了一个模型上下文协议（MCP）服务器，用于与JIRA和Zephyr集成。它允许AI助手通过标准化协议与JIRA进行项目管理交互，与Zephyr进行测试管理交互。

特性

创建包含摘要、描述、接受标准和问题类型的JIRA票证
使用灵活的JQL查询或按问题类型搜索JIRA票证
为故事票分配故事点数
自动为带有积分的故事创建链接的测试票
增强的错误处理功能，可自动重试自定义字段验证问题
更新为使用最新的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
- 窗户： %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": "your-email@example.com",
        "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”（默认）可自动为带有积分的故事票创建链接的测试票，或设置为“false”可禁用此功能

Zephyr集成

Zephyr集成需要这些环境变量来为测试票添加测试步骤：

ZAPI_BASE_URL：Zephyr API的基本URL（默认值：“https://prod-api.zephyr4jiracloud.com/connect")
ZAPI_ACCESS_KEY：您的Zephyr访问密钥（可在API密钥下的ZephyrCloud设置中找到）
ZAPI_SECRET_KEY：您的Zephyr密钥（可在API密钥下的ZephyrCloud设置中找到）
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：“是”选项的ID（默认值：“18258”）
JIRA_CRISIS_NO_ID：“否”选项的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": "your-email@example.com",
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_PROJECT_KEY": "your_project_key"
      }
    }
  }
}

查找自定义字段ID

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

在JIRA实例中打开工单
按F12打开开发人员工具
转到“网络”选项卡
刷新页面
寻找请求 issue/[ISSUE-KEY]
检查响应以查找自定义字段ID

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

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

可用工具

创建票证

创建新的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：覆盖自动创建链接测试票的默认设置（可选，布尔值）
parent_epic：链接此票的父史诗的密钥（可选，例如“PROJ-123”）
sprint：要将票分配给的冲刺的名称（可选，例如“2025_C1_S07”）
story_readiness：故事是否已准备好开发（可选，“是”或“否”）
crisis：此票是否代表危机/紧急问题（可选，“是”或“否”）

创建包含故事点数的故事票时：

“QA可测试”标签会自动添加到故事中
自动创建链接的测试票（如果 AUTO_CREATE_TEST_TICKETS 已启用）
测试票使用故事的标题作为描述
测试票通过“测试用例链接”关系链接到故事

例子：

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

买票

检索现有JIRA票证的详细信息。

参数：

ticket_id：您要读取的JIRA票证的ID/密钥（必填，例如“PROJ-123”）

例子：

{
  "ticket_id": "PROJ-123"
}

响应包括票证的所有字段，包括自定义字段。

搜索门票

按发行类型和其他条件搜索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条件来进一步优化您的搜索。

更新票证

用新的字段值更新现有的JIRA票证。

参数：

ticket_key：要更新的JIRA票证的密钥（必填，例如“PROJ-123”）
sprint：要将票分配给的冲刺的名称（可选，例如“2025_C1_S07”）
story_readiness：故事是否已准备好开发（可选，“是”或“否”）

例子：

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

此工具允许您使用冲刺信息和故事准备状态更新现有工单。必须至少提供一个字段才能继续更新。

链接票

将两个JIRA票证与指定的关系类型链接在一起。

参数：

outward_issue：外部问题的关键（必填，例如“PROJ-123”）
inward_issue：内部问题的关键（必填，例如“PROJ-456”）
link_type：要创建的链接类型（可选，默认为“测试用例链接”）

例子：

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

这将在具有指定关系类型的两个票证之间创建链接。例如，“PROJ-123阻止PROJ-456”。

获取测试步骤

从Zephyr测试票中检索测试步骤。

参数：

ticket_key：从中检索步骤的测试票密钥（必填，例如“PROJ-123”）

例子：

{
  "ticket_key": "PROJ-123"
}

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

添加测试步骤

通过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 服务器

应用程序使用以下命令创建MCP服务器 @modelcontextprotocol/sdk 包裹。该服务器公开了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);

搜索门票jcl

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

参数：

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

示例：

搜索特定门票： key = "PROJ-123"
按项目和状态搜索： project = "MYPROJECT" AND status = "In Progress"
按受让人搜索： assignee = "john.doe@company.com"
按多个条件搜索： project = "PROJ" AND issuetype = "Bug" AND priority = "High"

该工具为使用任何有效的JQL查询搜索JIRA票证提供了完全的灵活性。它使用更新的 /rest/api/3/search/jql 端点，以实现与当前JIRA Cloud实例的最佳兼容性。

JIRA集成

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

创建票证：创建具有可自定义字段的新JIRA票证
链接票：将两张JIRA票以指定的关系链接在一起
买票：检索有关特定JIRA票证的信息
搜索门票：使用JQL（JIRA查询语言）搜索JIRA票证
更新票证：用新信息更新现有的JIRA票证

该模块使用JIRA API的基本身份验证，并根据JIRA的Atlassian文档格式（ADF）格式化内容。

Zephyr集成

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

获取测试步骤：检索特定测试票的测试步骤
添加测试步骤：将测试步骤添加到测试票中

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

认证

JIRA身份验证

JIRA身份验证使用具有用户名和API令牌的基本身份验证：

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密钥使用HMAC-SHA256对JWT进行签名

数据格式

该项目包括根据JIRA的要求格式化数据的实用程序：

格式说明：设置JIRA票证描述的文本格式
格式接受标准：用适当的要点格式化验收标准

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

错误处理

该应用程序包括全面的错误处理：

检查API响应的成功状态代码
错误消息从API响应中提取（如果可用）
捕获并记录异常
错误信息以一致的格式返回给客户端

实用脚本

该项目在 util 帮助配置和设置任务的目录。

更新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设置问题

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

注：如果特定文件路径与默认路径不同，您可能需要修改脚本以匹配它们。

与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将使用创建票证工具在您的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
前往安全>API令牌
点击“创建API令牌”
为您的令牌命名（例如“Claude Integration”）
点击“创建”
复制令牌（您将无法再次看到它）

故障排除

如果您遇到问题：

检查您的JIRA凭据是否正确
验证配置中项目index.js文件的路径
确保你已经允许克劳德使用工具
检查Claude的控制台日志，查看是否有与JIRA MCP服务器相关的任何错误消息

使用说明

JIRA MCP集成

概述

目录

特性

安装

配置

配置位置

配置模板

基本配置

所需配置

可选配置

测试票创建

Zephyr集成

自定义字段配置

产品现场配置（可选）

类别字段配置（可选）

危机现场配置（可选）

最小配置示例

查找自定义字段ID

可用工具

创建票证

买票

搜索门票

更新票证

链接票

获取测试步骤

添加测试步骤

项目架构

核心组件

MCP 服务器

搜索门票jcl

JIRA集成

Zephyr集成

认证

JIRA身份验证

Zephyr身份验证

数据格式

错误处理

实用脚本

更新mcp-settings.js

与Claude一起使用

API更新和兼容性

已进行关键更新

弃用时间表

获取JIRA API代币

故障排除

相关 MCP

GitLab项目管理服务器

Primavera P6 XER文件解析服务器

Markdown微信排版发布工具

谷歌表格集成工具

JavaScript逆向标准化服务

OBS控制服务器