使用说明

JIRA MCP服务器

一个模型上下文协议（MCP）服务器，使Claude AI能够与JIRA进行交互，以进行项目管理、问题跟踪和发布计划。此服务器提供了Claude和JIRA实例之间的无缝集成。

特性

MCP工具

1. `search_jira_issues`

使用JQL（JIRA查询语言）搜索JIRA问题。

参数：

jql_query （str，必填）：JQL查询字符串
max_results （int，可选）：最大结果数（默认值：100）
include_comments （bool，可选）：包含问题注释（默认值：False）

例子：

search_jira_issues(
    jql_query="project = MYPROJECT AND status != Closed",
    max_results=50,
    include_comments=True
)

2. `get_jira_issue_details` （增强）

获取有关特定JIRA问题的全面详细信息，包括子任务和链接问题。

参数：

issue_key （str，必填）:JIRA问题密钥（例如“PROJECT-123”）
include_comments （bool，可选）：包含注释（默认值：True）
include_subtasks （bool，可选）：包括子问题/子任务（默认值：True）
include_linked_issues （bool，可选）：包含链接类型的相关问题（默认值：True）

退货：

{
  "status": "success",
  "message": "Retrieved issue PROJECT-123",
  "issue": {
    "key": "PROJECT-123",
    "summary": "Implement New Feature",
    "description": "Add support for the new feature...",
    "status": "In Progress",
    "type": "Story",
    "priority": "High",
    "assignee": "John Doe",
    "reporter": "Jane Smith",
    "created": "2025-01-01T10:00:00.000+0000",
    "updated": "2025-01-15T15:30:00.000+0000",
    "fix_versions": ["Release 1.0", "Release 2.0"],
    "labels": ["BETA6", "JC_Validation_Clear"],
    "comments": [
      {
        "author": "John Doe",
        "created": "2025-01-10T12:00:00.000+0000",
        "body": "Started implementation"
      }
    ],
    "subtasks": [
      {
        "key": "PROJECT-124",
        "summary": "Design API",
        "status": "Done",
        "type": "Sub-task"
      },
      {
        "key": "PROJECT-125",
        "summary": "Implement Parser",
        "status": "In Progress",
        "type": "Sub-task"
      }
    ],
    "linked_issues": [
      {
        "link_type": "blocks",
        "key": "PROJECT-100",
        "summary": "Hardware Support",
        "status": "Open"
      },
      {
        "link_type": "relates to",
        "key": "PROJECT-200",
        "summary": "Related Feature",
        "status": "In Progress"
      }
    ]
  }
}

例子：

# Get full issue details with all relationships
get_jira_issue_details("PROJECT-123")

# Get issue without comments
get_jira_issue_details("PROJECT-123", include_comments=False)

# Get only basic issue info (no relations)
get_jira_issue_details(
    "PROJECT-123",
    include_comments=False,
    include_subtasks=False,
    include_linked_issues=False
)

3. `add_jira_comment`

为JIRA问题添加评论。

参数：

issue_key （str，必填）:JIRA问题密钥（例如“PROJECT-123”）
comment_body （str，必填）：JIRA wiki标记格式的注释文本

注： JIRA使用wiki标记，而不是markdown。请参阅文档字符串中的格式规则。

4. `edit_jira_comment`

编辑关于JIRA问题的现有评论。

参数：

issue_key （str，必填）:JIRA问题密钥
comment_id （str，必填）：要编辑的评论的ID
comment_body （str，必填）：JIRA wiki标记格式的新评论文本

5. `update_jira_issue`

更新JIRA问题的字段。只有明确提供的字段才会被更新。

参数：

issue_key （str，必填）:JIRA问题密钥（例如“PROJECT-123”）
summary （str，可选）：新问题标题/摘要
description （str，可选）：JIRA wiki标记格式的新描述
priority （str，可选）：优先级名称-“最高”、“高”、“中”、“低”、“最低”
assignee （str，可选）：用户名或帐户ID。使用空字符串 "" 取消分配
labels （list，可选）：标签字符串数组。替换所有现有标签
- 注意：JIRA标签不能包含空格——使用下划线（例如。， "JC_Validation_Clear").JIRA的web UI将下划线显示为空格。
fix_versions （list，可选）：版本名称数组。替换现有版本
- ⚠️ 警告： 修复版本通常由发布经理管理
team （str，可选）：团队名称（使用可配置的自定义字段ID）

例子：

# Update single field
update_jira_issue("PROJECT-123", summary="New Title")

# Update multiple fields
update_jira_issue(
    "PROJECT-123",
    summary="Updated Title",
    priority="High",
    description="New description with *bold* text"
)

# Update labels (replaces all existing)
update_jira_issue("PROJECT-123", labels=["bug", "urgent"])

# Unassign issue
update_jira_issue("PROJECT-123", assignee="")

# Update team
update_jira_issue("PROJECT-123", team="Platform Team")

退货：

{
  "status": "success",
  "message": "Updated PROJECT-123: summary, priority",
  "updated_fields": ["summary", "priority"],
  "issue": {
    "key": "PROJECT-123",
    "summary": "Updated Title",
    ...
  }
}

6. `rank_jira_issues`

使用JIRA的敏捷排名API将一个或多个JIRA问题相对于另一个问题进行排名（重新排序）。

参数：

issue_keys （列表，必填）：要移动的问题密钥列表（最多50个）
rank_before （str，可选）：将问题排在此问题密钥之前（优先级较高）
rank_after （str，可选）：将问题排在此问题密钥之后（优先级较低）

注：精确指定以下之一 rank_before 或 rank_after.

例子：

# Move single issue to top of backlog (before first issue)
rank_jira_issues(["PROJECT-10"], rank_before="PROJECT-1")

# Move multiple issues after a specific issue
rank_jira_issues(["PROJECT-5", "PROJECT-6", "PROJECT-7"], rank_after="PROJECT-2")

退货：

status: "success" -所有问题均已成功排序
status: "partial" -一些问题失败（包括 successes 和 failures 阵列）
status: "error" -完全失败，并显示错误消息

权限： 需要JIRA中的“计划问题”权限。

7. `reorder_jira_issues`

便利功能，通过链接排名操作将多个问题重新排序到特定序列中。

参数：

issue_keys （列表，必填）：按所需顺序排列的问题（第一个=最高优先级）
after_issue （str，可选）：引用问题，将所有问题放在后面

例子：

# Reorder issues in sequence (first issue becomes highest priority)
reorder_jira_issues([
    "PROJECT-100",  # First (highest priority)
    "PROJECT-101",  # Second
    "PROJECT-102",  # Third
])

# Place issues after a reference point
reorder_jira_issues(["PROJECT-5", "PROJECT-6"], after_issue="PROJECT-1")

退货： 成功/错误状态 operations_completed 计数

关键增强功能

🎯 单个API调用效率

增强 get_jira_issue_details 使用JIRA的扩展参数在单个API调用中获取问题详细信息、子任务和链接的问题，从而减少延迟和API的使用。

🔗 自动关系解决

不需要单独的JQL查询，如：

❌ parent = PROJECT-123 （用于子任务）
❌ issue in linkedIssues(PROJECT-123) （针对相关问题）

一切都是自动提取的！

🎛️ 灵活的选项

通过对注释、子任务和链接问题的精细控制，准确选择所需的数据。

安装

先决条件

Python 3.8+
JIRA API承载令牌

设置

克隆或下载存储库
安装依赖项：

pip install -r requirements.txt

关键依赖关系：

fastmcp==0.4.1 -MCP服务器框架
mcp==1.5.0 -模型上下文协议SDK
requests==2.32.3 -JIRA API的HTTP客户端

设置环境变量：

创建一个 .env 文件或设置环境变量：

export JIRA_SERVER_URL="https://your-jira-instance.atlassian.net"
export JIRA_API_TOKEN="your_jira_bearer_token_here"

在Windows上：

set JIRA_SERVER_URL=https://your-jira-instance.atlassian.net
set JIRA_API_TOKEN=your_jira_bearer_token_here

获取您的JIRA API代币

登录您的JIRA实例
导航到配置文件→ 个人访问令牌
创建具有适当权限的新令牌
复制令牌并安全存储

所需权限：

阅读问题
浏览项目
查看评论

用法

启动MCP服务器

python jira_mcp_tool.py

服务器将启动并监听来自Claude的MCP协议消息。

与Claude Desktop一起使用

添加到您的Claude Desktop MCP配置中：

macOS/Linux： ~/.config/claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "jira": {
      "command": "python",
      "args": ["/path/to/jira_mcp_server.py"],
      "env": {
        "JIRA_SERVER_URL": "https://your-jira-instance.atlassian.net",
        "JIRA_API_TOKEN": "your_token_here"
      }
    }
  }
}

示例工作流程

1.发现和分析问题

User: "Find all high-priority bugs in my project that are still open"

Claude uses: search_jira_issues(
    jql_query="project = MYPROJECT AND type = Bug AND priority = High AND status = Open"
)

2.获取完整的问题背景

User: "Show me all details about PROJECT-123 including what it blocks and its subtasks"

Claude uses: get_jira_issue_details("PROJECT-123")

Result includes:
- Issue details
- All subtasks
- All linked issues (blocks, is blocked by, relates to, etc.)
- Comments

3.发布计划分析

User: "Analyze the completion status of PROJECT-123 and its dependencies"

Claude uses:
1. get_jira_issue_details("PROJECT-123") - gets issue with all relations
2. Analyzes subtasks completion
3. Checks linked issues status
4. Provides comprehensive report

4.安全标签操作

User: "Add the 'reviewed' label to PROJECT-123 without removing existing labels"

Claude uses:
1. get_jira_issue_details("PROJECT-123") - read current labels
2. Append new label: current_labels + ["reviewed"]
3. update_jira_issue("PROJECT-123", labels=new_labels)

This prevents accidentally wiping out existing labels like "BETA6" or "urgent"

5.待办事项重新排序

User: "Reorder these issues so they're prioritized in this order: PROJECT-100, PROJECT-101, PROJECT-102"

Claude uses: reorder_jira_issues([
    "PROJECT-100",  # Highest priority
    "PROJECT-101",  # Second
    "PROJECT-102"   # Third
])

Result: Issues are ranked in sequence in the backlog

建筑

组件概览

┌─────────────────────────────────────────────────┐
│            Claude AI Assistant                   │
└─────────────────┬───────────────────────────────┘
                  │ MCP Protocol
                  ▼
┌─────────────────────────────────────────────────┐
│          FastMCP Server Framework                │
│  ┌───────────────────────────────────────────┐  │
│  │  @mcp.tool()                              │  │
│  │  - search_jira_issues()                   │  │
│  │  - get_jira_issue_details()               │  │
│  │  - add_jira_comment()                     │  │
│  │  - edit_jira_comment()                    │  │
│  │  - update_jira_issue()                    │  │
│  │  - rank_jira_issues()                     │  │
│  │  - reorder_jira_issues()                  │  │
│  └───────────────────────────────────────────┘  │
└─────────────────┬───────────────────────────────┘
                  │ HTTPS/Bearer Token
                  ▼
┌─────────────────────────────────────────────────┐
│         JIRA REST API v2                         │
│  - /rest/api/2/search (JQL queries)             │
│  - /rest/api/2/issue/{key}?expand=...           │
│  - /rest/api/2/issue/{key}/comment              │
└─────────────────────────────────────────────────┘

使用的API端点

函数	端点	方法	目的
`search_jira_issues`	`/rest/api/2/search`	基于GET	JQL的问题搜索
`get_issue_with_relations`	`/rest/api/2/issue/{key}?expand=subtasks,issuelinks`	GET	单一关系问题
`get_issue_comments`	`/rest/api/2/issue/{key}/comment`	GET	发布评论
`add_jira_comment`	`/rest/api/2/issue/{key}/comment`	POST	添加评论
`edit_jira_comment`	`/rest/api/2/issue/{key}/comment/{id}`	PUT	编辑评论
`update_jira_issue`	`/rest/api/2/issue/{key}`	PUT	更新问题字段
`rank_jira_issues`	`/rest/agile/1.0/issue/rank`	PUT	对积压的问题进行排序

数据流

get_jira_issue_details("PROJECT-123", include_subtasks=True, include_linked_issues=True)
    │
    ├─→ get_issue_with_relations()
    │       │
    │       └─→ GET /rest/api/2/issue/PROJECT-123?expand=subtasks,issuelinks
    │               │
    │               └─→ Returns: issue + subtasks + linked issues
    │
    ├─→ get_issue_comments()
    │       │
    │       └─→ GET /rest/api/2/issue/PROJECT-123/comment
    │               │
    │               └─→ Returns: comments list
    │
    └─→ Combine data and return comprehensive response

测试

运行单元测试

# Using pytest
python -m pytest test_jira_mcp_tool.py -v

# Using unittest
python -m unittest test_jira_mcp_tool.py

测试覆盖率

测试套件包括：

✅ 获取子任务的问题
✅ 将问题与关联问题联系起来
✅ 标签问题
✅ 处理没有关系的问题
✅ 可选参数组合
✅ 错误处理（404，API错误，异常）
✅ 输入验证
✅ 缺少身份验证令牌
✅ 向后兼容
✅ 问题排名（单个和批量）
✅ 批量重新排序操作

手动测试

用真实的JIRA问题测试服务器：

# Start the server
python jira_mcp_server.py

# In Claude Desktop, try:
# "Get details about PROJECT-123"
# "Find all open bugs in project MYPROJECT"

配置

环境变量

变量	必填	描述
`JIRA_SERVER_URL`	是	您的JIRA实例URL（例如。， `https://your-company.atlassian.net`)
`JIRA_API_TOKEN`	是	JIRA身份验证的承载令牌

发展

项目结构

.
├── jira_mcp_server.py        # Main MCP server implementation
├── test_jira_mcp_tool.py     # Unit tests
├── util.py                   # Utility functions
├── requirements.txt          # Python dependencies
├── README.md                 # This file
├── LICENSE                   # MIT License
└── .env                      # Environment variables (git-ignored)

添加新工具

要添加新的MCP工具：

定义函数 @mcp.tool() 装饰师：

@mcp.tool()
def my_new_tool(param: str) -> Dict[str, Any]:
    """Tool description for Claude."""
    # Implementation
    return {"status": "success", "data": ...}

在中添加测试 test_jira_mcp_tool.py
更新此自述文件

代码风格

为所有函数参数和返回值键入提示
全面的文档字符串（谷歌风格）
try/except块的错误处理
从JIRA响应中提取空安全字段

故障排除

常见问题

身份验证错误

Error: JIRA_API_TOKEN not found in environment variables

解决方案： 设置 JIRA_API_TOKEN 环境变量。

连接错误

Error: JIRA API error: 401 - Unauthorized

解决方案：

检查您的令牌是否有效
确保令牌具有所需的权限
验证令牌是否未过期

缺少JIRA服务器URL

Error: JIRA_SERVER_URL not found in environment variables

解决方案： 设置 JIRA_SERVER_URL 环境变量到JIRA实例URL。

404错误

Error: Issue PROJECT-123 not found

解决方案：

验证问题密钥是否正确
检查您是否有权限查看该问题
确保JIRA中存在该问题

导入错误

ModuleNotFoundError: No module named 'fastmcp'

解决方案： 安装依赖项：

pip install -r requirements.txt

调试模式

要启用调试输出，请在中取消注释print语句 jira_mcp_server.py:

if __name__ == "__main__":
    print("Starting JIRA MCP Server...")  # Uncomment for debug
    mcp.run()

安全考虑

令牌存储

✅ 将令牌存储在环境变量中或进行安全的秘密管理
❌ 从不将令牌提交到版本控制
❌ 永远不要在源文件中硬编码令牌

API权限

授予所需的最小权限：

阅读问题
浏览项目
查看评论
编辑问题（必填） update_jira_issue)
添加评论（必填） add_jira_comment)

避免：

管理员权限
问题创建（除非需要）
项目管理
删除权限

网络安全

所有API调用都使用HTTPS
承载令牌身份验证
代码中未存储凭据

演出

API调用优化

增强 get_jira_issue_details 减少了API调用：

之前：

1. GET /rest/api/2/search (get issue)
2. GET /rest/api/2/search?jql=parent=PROJECT-123 (get subtasks)
3. GET /rest/api/2/search?jql=issue in linkedIssues(...) (get links)
4. GET /rest/api/2/issue/{key}/comment (get comments)
Total: 4 API calls

之后：

1. GET /rest/api/2/issue/{key}?expand=subtasks,issuelinks (get all)
2. GET /rest/api/2/issue/{key}/comment (get comments)
Total: 2 API calls (50% reduction)

速率限制

JIRA Cloud通常限制：

每位用户每分钟约300个请求
每个应用程序每天约100000个请求

此服务器不包含内置速率限制。对于高容量使用，考虑添加：

请求限制
响应缓存
指数退避

更新日志

版本2.2（当前）

待办列表排名和标签支持

✨ 添加 rank_jira_issues() 使用JIRA的敏捷API对问题进行排名的工具
✨ 添加 reorder_jira_issues() 批量重新排序的便利工具
✨ 添加 labels 领域到 search_jira_issues() 和 get_jira_issue_details() 回应
🎯 启用安全“读取”→ 附加→ 为标签编写工作流程
⚡ 批量排名支持每次通话最多50个问题
✅ 22个用于排名和标签功能的新单元测试

版本2.1

问题编辑能力

✨ 添加 update_jira_issue() 用于更新问题字段的工具
✨ 添加 get_jira_field_metadata() 用于发现自定义字段ID的助手
🎛️ 支持：摘要、描述、优先级、受让人、标签、修订版本、团队
⚠️ 修复版本包括关于发布管理协调的警告
📝 仅提供更新字段；省略的字段保持不变
✅ 17个用于更新功能的新单元测试

版本2.0

增强的get_jira_issue_details

✨ 添加了自动子任务检索
✨ 添加了自动链接问题检索
✨ 添加了用于粒度控制的可选参数
⚡ 优化为使用带有扩展参数的单个API调用
📝 全面的文档字符串和类型提示
✅ 全面测试覆盖

版本1.0

初始版本

基础 search_jira_issues 功能
基础 get_jira_issue_details 功能
承载令牌身份验证

贡献

指南

代码质量
- 添加类型提示
- 编写文档字符串
- 遵循现有模式
测试
- 为新功能添加单元测试
- 确保所有测试通过
- 保持>80%的覆盖率
文档
- 更新README以获取新功能
- 为复杂逻辑添加内联注释
- 包括使用示例

提交变化

彻底测试您的更改
更新测试和文档
提交时明确说明变更

许可证

MIT许可证-请参阅许可证文件以获取详细信息。

支持

对于问题或疑问：

检查故障排除部分
查看JIRA REST API文档
检查MCP协议文件https://modelcontextprotocol.io

参考文献

实现基于人工智能的JIRA分析和项目管理

使用说明

JIRA MCP服务器

特性

MCP工具

1. search_jira_issues

2. get_jira_issue_details （增强）

3. add_jira_comment

4. edit_jira_comment

5. update_jira_issue

6. rank_jira_issues

7. reorder_jira_issues

关键增强功能

🎯 单个API调用效率

🔗 自动关系解决

🎛️ 灵活的选项

安装

先决条件

设置

获取您的JIRA API代币

用法

启动MCP服务器

与Claude Desktop一起使用

示例工作流程

1.发现和分析问题

2.获取完整的问题背景

3.发布计划分析

4.安全标签操作

5.待办事项重新排序

建筑

组件概览

使用的API端点

数据流

测试

运行单元测试

测试覆盖率

手动测试

配置

环境变量

发展

项目结构

添加新工具

代码风格

故障排除

常见问题

身份验证错误

连接错误

缺少JIRA服务器URL

404错误

导入错误

调试模式

安全考虑

令牌存储

API权限

网络安全

演出

API调用优化

速率限制

更新日志

版本2.2（当前）

版本2.1

版本2.0

版本1.0

贡献

指南

提交变化

许可证

支持

参考文献

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

Flomo笔记服务

GitLab项目管理服务器

Unity编辑器AI集成插件

1. `search_jira_issues`

2. `get_jira_issue_details` （增强）

3. `add_jira_comment`

4. `edit_jira_comment`

5. `update_jira_issue`

6. `rank_jira_issues`

7. `reorder_jira_issues`