使用说明
JIRA MCP服务器
这是一个模型上下文协议（MCP）服务器，提供与JIRA交互的工具。它允许您从活动的sprint中获取工单、搜索问题、管理用户，并通过MCP界面获取详细的工单信息。
⚠️ 更新至2025年：该fork包括对Atlassian的API弃用的关键修复，该弃用在原始版本中导致410个错误。所有弃用的端点都已被其现代等效端点所取代。
特性
服务器提供以下工具：
问题管理
-
search-issues：使用JQL或筛选器搜索问题- 可选参数：
jql（string）-自定义JQL查询 - 可选参数：
projectKey（string）-按项目筛选 - 可选参数：
issueType（string）-按问题类型筛选（例如，“Bug”、“任务”、“故事”） - 可选参数：
statusCategory（string）-按状态筛选（“待办事项”、“进行中”、“完成”） - 可选参数：
maxResults（number）-返回的最大结果数（默认值：20，最大值：100） - 可选参数：
startAt（数字）-分页偏移
- 可选参数：
-
list-sprint-tickets：获取给定项目的活动sprint中的所有票证- 必需参数：
projectKey（字符串）
- 必需参数：
-
get-ticket-details：获取特定票证的详细信息- 必需参数：
issueKey（字符串）
- 必需参数：
-
add-comment：向特定票证添加注释- 必需参数：
issueKey（字符串） - 必需参数：
comment（字符串）
- 必需参数：
-
update-description：更新特定票证的描述- 必需参数：
issueKey（字符串） - 必需参数：
description（字符串）
- 必需参数：
-
list-child-issues：获取父票证的所有子问题- 必需参数：
parentKey（字符串）
- 必需参数：
-
create-sub-ticket：为父票创建子票（子票）- 必需参数：
parentKey（字符串） - 必需参数：
summary（字符串） - 可选参数：
description（字符串） - 可选参数：
issueType（string）-子任务问题类型的名称（例如，“子任务”）
- 必需参数：
-
create-ticket：使用自定义字段创建新票证- 必需参数：
projectKey（字符串） - 必需参数：
summary（字符串） - 可选参数：
description（字符串） - 可选参数：
issueType（字符串） - 可选参数：
parentKey（string）-如果提供，则创建子任务 - 可选参数：
fields（object）-其他自定义字段
- 必需参数：
-
update-issues：批量更新多张票上的字段- 必需参数：
issueKeys（字符串数组） - 必需参数：
fields（对象）-要更新的字段
- 必需参数：
-
add-labels：为多个问题添加标签- 必需参数：
issueKeys（字符串数组） - 必需参数：
labels（字符串数组）
- 必需参数：
-
link-issues：使用“关联”关系链接多张票- 必需参数：
inwardIssueKeys（字符串数组） - 必需参数：
outwardIssueKeys（字符串数组）
- 必需参数：
-
transition-issues：将多个问题转换为新的状态- 必需参数：
issueKeys（字符串数组） - 必需参数：
transitionId（字符串）
- 必需参数：
-
list-issue-transitions：列出问题的可用转换- 必需参数：
issueKey（字符串）
- 必需参数：
-
assign-issue：将问题分配给用户- 必需参数：
issueKeys（字符串数组） - 必需参数：
assigneeDisplayName（字符串）
- 必需参数：
用户和现场管理
-
list-users：列出Jira中的所有用户- 可选参数：
query（string）-用于筛选用户的搜索字符串 - 可选参数：
maxResults（数字）-最大结果（默认值：50，最大值：1000）
- 可选参数：
-
list-issue-fields：列出所有可用的问题字段，包括自定义字段- 可选参数：
includeCustomOnly（boolean）-仅显示自定义字段
- 可选参数：
-
list-jira-filters：列出所有Jira筛选器
设置
-
安装依赖项：
npm install -
构建TypeScript代码：
此步骤仅适用于Windows上的Cline，目前在执行npx时遇到问题
npm run build
- 在Claude应用程序设置文件中配置MCP设置（通常位于
~/Library/Application Support/Claude/claude_desktop_config.json在macOS或%APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json在Windows上）：
克劳德的设置：
{
"mcpServers": {
"jira": {
"command": "npx",
"args": ["path/to/this/repo/jira.ts"],
"env": {
"JIRA_HOST": "https://your-domain.atlassian.net",
"JIRA_EMAIL": "your-email@example.com",
"JIRA_API_TOKEN": "your-api-token"
}
}
}
}
Cline的设置：
{
"mcpServers": {
"jira": {
"command": "node",
"args": ["path/to/this/repo/dist/jira.js"],
"env": {
"JIRA_HOST": "https://your-domain.atlassian.net",
"JIRA_EMAIL": "your-email@example.com",
"JIRA_API_TOKEN": "your-api-token"
}
}
}
}
配置
选项1：使用.env文件进行本地开发
对于本地开发和测试，您可以使用 .env 文件：
-
复制示例文件：
cp .env.example .env -
编辑
.env并添加您的凭据：JIRA_HOST=https://your-domain.atlassian.net JIRA_EMAIL=your-email@example.com JIRA_API_TOKEN=your-api-token -
运行服务器：
npm start
选项2:MCP配置
您需要在MCP设置中设置以下环境变量：
JIRA_HOST：您的Atlassian域URL（例如。，https://your-company.atlassian.net)JIRA_EMAIL：您的JIRA帐户电子邮件JIRA_API_TOKEN：您的JIRA API代币- 您可以从您的 Atlassian帐户设置
用法
配置后，您可以通过Claude中的MCP接口使用这些工具：
列出Sprint门票
要获取项目活动sprint中的所有票，请执行以下操作：
<use_mcp_tool>
<server_name>jira</server_name>
<tool_name>list-sprint-tickets</tool_name>
<arguments>
{
"projectKey": "YOUR_PROJECT_KEY"
}
</arguments>
</use_mcp_tool>
获取门票详细信息
要获取特定票证的详细信息，请执行以下操作：
<use_mcp_tool>
<server_name>jira</server_name>
<tool_name>get-ticket-details</tool_name>
<arguments>
{
"issueKey": "PROJECT-123"
}
</arguments>
</use_mcp_tool>
发展
服务器是用TypeScript编写的，使用：
@modelcontextprotocol/sdk用于MCP服务器实现jira.js用于JIRA API集成
推荐脚本：
- 构建一次：
npm run build - 构建和观看：
npm run build:watch - 仅类型检查：
npm run typecheck - 戴手表跑步：
npm run start:dev - 运行已编译的服务器：
npm start - 格式检查：
npm run fmt:check - 格式写入：
npm run fmt
典型工作流程：
- 对以下内容进行更改
jira.ts - 跑
npm run start:dev在开发过程中，或npm run build然后npm start用于编译运行 - 如果需要获取更改，请重新启动MCP客户端
最近更新（2025）
Atlassian API弃用的关键修复程序
此分叉包括对以下导致410 Gone错误的已弃用端点的修复：
-
/rest/api/3/users/search→ 迁移到/rest/api/3/user/search- 影响：
list-users工具 - 已修复：已更新以供使用
userSearch.findUsers()有适当的分页
- 影响：
-
/rest/api/3/search→ 迁移到/rest/api/3/search/jql- 影响：
search-issues和list-sprint-tickets工具 - 已修复：已更新以供使用
searchForIssuesUsingJqlEnhancedSearch()基于令牌的分页 - 注意：新的API需要有边界的JQL查询（无边界查询现在默认为持续30天）
- 影响：
其他改进
- 更新
jira.js从4.1.3到5.2.2的依赖关系 - 添加
.env本地开发的文件支持dotenv - 增强的错误消息，包含完整的响应详细信息，便于调试
- 添加了测试脚本(
test-local.sh)促进地方发展 - 使用新的基于令牌的系统改进分页处理
错误处理
服务器包括以下错误处理：
- JIRA凭据无效
- 缺少主动冲刺
- 项目密钥或问题密钥无效
- 网络错误
- 已弃用的API端点（自动迁移到新端点）
错误消息将在工具响应中返回，并包含详细信息。
从原始版本迁移
如果您从原始版本迁移 boukeversteegh/mcp-server-jira:
-
更新您的本地存储库：
git pull npm install npm run build -
重新启动MCP客户端（Cursor/Claude）
-
所有工具现在都应该可以正常工作，没有410个错误
贡献
欢迎投稿！请随时提交拉取请求。
许可证
Apache-2.0许可证