JIRA MCP 工具

一个用于通过 Claude Desktop 与 JIRA API 交互的模型上下文协议 (MCP)。

功能

• 使用 JQL（JIRA 查询语言）搜索 JIRA 问题
• 列出已验证用户的 JIRA 项目
• 创建、更新和删除 JIRA 问题
• 添加评论并在状态之间转换问题
• 搜索用户（支持 GDPR 合规性）

安装

1. 克隆此存储库：

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

2. 创建并激活虚拟环境：

   # On macOS/Linux
   python -m venv venv
   source venv/bin/activate
   
   # On Windows
   python -m venv venv
   .\venv\Scripts\activate
   

3. 安装依赖项：

   pip install -r requirements.txt
   

4. 在项目根目录中创建一个 .env 文件：

   touch .env
   

5. 将您的 JIRA 凭据添加到 .env 文件：

   JIRA_SERVER=https://your-domain.atlassian.net
   JIRA_EMAIL=your.email@example.com
   JIRA_API_TOKEN=your_api_token_here
   

6. 测试安装：

   # 运行所有测试
   python -m pytest
   
   # 运行特定的测试文件
   python -m pytest tests/test_search_issues.py
   

7. 启动 MCP 服务器：

   python run.py
   

环境设置

JIRA API 令牌

您需要一个 JIRA API 令牌才能通过 JIRA 实例进行身份验证：

1. 登录到您的 Atlassian 帐户
2. 转到帐户设置 > 安全性 > 创建和管理 API 令牌
3. 单击“创建 API 令牌”
4. 为其命名（例如，“Claude Desktop Integration”）
5. 单击“创建”并安全地保存生成的令牌

GDPR 合规性

如果您使用的是 JIRA Cloud 实例（很可能处于 GDPR 严格模式）：

1. 用户搜索将仅匹配显示名称和电子邮件地址
2. 不支持基于用户名的搜索
3. 结果可能会受到用户权限的限制
4. 该工具会自动处理 GDPR 要求，但您可能需要调整搜索模式

故障排除

常见问题和解决方案：

1. ModuleNotFoundError: No module named 'src'

   # 使用设置的 PYTHONPATH 运行
   PYTHONPATH=/path/to/mcp-jira python run.py
   

2. JIRA API 身份验证错误

   • 验证您的 API 令牌是否正确
   • 检查您的电子邮件是否与您的 Atlassian 帐户匹配
   • 确保您的 JIRA 实例 URL 正确且包含“https://”

3. GDPR 相关错误

   • 如果您看到“username parameter not supported”错误，则您的实例处于 GDPR 模式
   • 使用显示名称或电子邮件地址进行搜索，而不是用户名
   • 该工具将自动调整 API 调用以符合 GDPR

获取 JIRA API 令牌

1. 登录到您的 Atlassian 帐户
2. 转到帐户设置 > 安全性 > 创建和管理 API 令牌
3. 单击“创建 API 令牌”
4. 为其命名（例如，“Claude Desktop Integration”）
5. 单击“创建”并安全地保存生成的令牌

工具

搜索问题

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

参数：

• jql：JIRA 查询语言字符串（例如，“project=DEMO AND status=Open”）
• max_results：要返回的最大结果数（默认值：10）
• fields：要包含在结果中的字段的逗号分隔列表（默认值：“summary,status,assignee,priority,issuetype”）

创建问题

在指定的项目中创建一个新的 JIRA 问题。

参数：

• project_key：要在其中创建问题的项目的键（例如，“DEMO”）
• summary：问题摘要
• description：问题描述（可选）
• issue_type：问题类型（默认值：“Task”，可以是“Bug”、“Story”等）
• priority：问题的优先级（可选，例如，“High”、“Medium”、“Low”）
• assignee：要将问题分配给的用户名（可选）

更新问题

使用新值更新现有的 JIRA 问题。

参数：

• issue_key：JIRA 问题键（例如，“PROJ-123”）
• summary：问题的新摘要（可选）
• description：问题的新描述（可选）
• status：问题的新状态（可选，例如，“In Progress”、“Done”）
• priority：问题的新优先级（可选，例如，“High”、“Medium”、“Low”）
• assignee：问题的新受让人（可选）
• comment：要添加到问题的评论（可选）

删除问题

删除 JIRA 问题（需要明确确认）。

参数：

• issue_key：JIRA 问题键（例如，“PROJ-123”）
• confirm：防止意外删除的确认标志，必须设置为 True

列出项目

列出已验证用户的 JIRA 项目。

参数：

• limit：要返回的最大项目数（默认值：10）

添加评论

向现有的 JIRA 问题添加评论。

参数：

• issue_key：JIRA 问题键（例如，“PROJ-123”）
• comment：要添加到问题的评论文本

转换问题

将 JIRA 问题转换为新状态。

参数：

• issue_key：JIRA 问题键（例如，“PROJ-123”）
• status：要将问题转换到的目标状态（例如，“In Progress”、“Done”）
• comment：与转换一起添加的可选评论

获取问题详情

获取有关 JIRA 问题的详细信息。

参数：

• issue_key：JIRA 问题键（例如，“PROJ-123”）
• include_comments：是否在响应中包含问题评论（默认值：False）

搜索用户

按姓名、电子邮件或用户名搜索 JIRA 用户。 此工具可帮助您在需要分配问题或添加观察者时查找用户。

重要提示：对于启用了 GDPR 严格模式的 JIRA Cloud 实例（这是较新实例的默认设置），用户搜索必须使用 query 参数而不是 username。 该工具会自动处理此问题，但您可能需要相应地调整搜索模式。

参数：

• query (str)：用于匹配用户显示名称和电子邮件地址的搜索字符串
  • 对于符合 GDPR 的实例，这将搜索显示名称和电子邮件地址
  • 搜索不区分大小写并匹配部分字符串
  • 示例：“john”将匹配“John Doe”和“johnny@example.com”
• max_results (int, optional)：要返回的最大用户数（默认值：10）
• include_active_users (bool, optional)：在搜索结果中包含活动用户（默认值：True）
• include_inactive_users (bool, optional)：在搜索结果中包含非活动用户（默认值：False）

用法示例：

# 搜索显示名称或电子邮件中包含“john”的用户
search_users(query="john")

# 搜索最多 20 个用户，包括非活动用户
search_users(
    query="smith",
    max_results=20,
    include_inactive_users=True
)

GDPR 合规性说明：

• 在 GDPR 严格模式下，用户搜索更具限制性，以保护用户隐私
• 搜索仅匹配用户显示名称和电子邮件地址
• 不支持完全用户名匹配
• 搜索始终不区分大小写
• 支持部分匹配（例如，“jo”将匹配“John”）
• 结果可能会受到用户的权限和隐私设置的限制

使用示例

搜索 PROJECT 中优先级高的错误：
search_issues(jql="project=PROJECT AND issuetype=Bug AND priority=High")

在 PROJECT 中创建一个新错误：
create_issue(project_key="PROJECT", summary="登录按钮无法正常工作", description="用户无法使用主页上的登录按钮登录", issue_type="Bug", priority="High")

更新现有问题：
update_issue(issue_key="PROJECT-123", summary="已更新：登录按钮已修复", status="In Progress", comment="修复了 CSS 样式问题")

删除问题：
delete_issue(issue_key="PROJECT-123", confirm=True)

列出前 5 个项目：
list_projects(limit=5)

向问题添加评论：
add_comment(issue_key="PROJECT-123", comment="该修复程序已部署到生产环境")

转换问题：
transition_issue(issue_key="PROJECT-123", status="In Progress", comment="开始处理此问题")

获取问题详情：
get_issue_details(issue_key="PROJECT-123", include_comments=True)

开发

对于想要修改或扩展此 MCP 的开发人员：

1. 克隆存储库
2. 设置虚拟环境：python -m venv venv && source venv/bin/activate
3. 安装依赖项：pip install -r requirements.txt
4. 运行测试：python -m pytest
5. 进行更改
6. 使用 Claude Desktop 进行测试