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. 测试安装：
   # Run all tests python -m pytest # Run a specific test file 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. 点击“创建”，并安全保存生成的token

GDPR 合规性

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

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

故障排除

常见问题及解决方案：

1. ModuleNotFoundError：没有名为“src”的模块
   # Run with PYTHONPATH set PYTHONPATH=/path/to/mcp-jira python run.py
2. JIRA API 身份验证错误
   • 验证您的 API 令牌是否正确
   • 检查您的电子邮件是否与您的 Atlassian 帐户相符
   • 确保您的 JIRA 实例 URL 正确且包含“https://”
3. GDPR相关错误
   • 如果您看到“不支持用户名参数”错误，则表示您的实例处于 GDPR 模式
   • 使用显示名称或电子邮件地址而不是用户名进行搜索
   • 该工具将自动调整 API 调用以符合 GDPR 要求

获取 JIRA API 令牌

1. 登录您的 Atlassian 帐户
2. 前往“帐户设置”>“安全”>“创建和管理 API 令牌”
3. 点击“创建 API 令牌”
4. 给它起个名字（例如，“Claude Desktop Integration”）
5. 点击“创建”，并安全保存生成的token

工具

搜索问题

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

参数：

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

创建问题

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

参数：

• project_key：创建问题的项目的密钥（例如“DEMO”）
• summary：问题摘要
• 描述：问题描述（可选）
• issue_type：问题类型（默认值：“任务”，可以是“Bug”、“Story”等）
• 优先级：问题的优先级（可选，例如“高”、“中”、“低”）
• 受让人：分配问题的用户名（可选）

更新问题

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

参数：

• issue_key：JIRA 问题密钥（例如“PROJ-123”）
• 摘要：问题的新摘要（可选）
• 描述：问题的新描述（可选）
• status：问题的新状态（可选，例如“进行中”、“完成”）
• 优先级：问题的新优先级（可选，例如“高”、“中”、“低”）
• 受让人：问题的新受让人（可选）
• 评论：添加到问题的评论（可选）

删除问题

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

参数：

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

列出项目

列出经过身份验证的用户的 JIRA 项目。

参数：

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

添加评论

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

参数：

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

过渡问题

将 JIRA 问题转换为新状态。

参数：

• issue_key：JIRA 问题密钥（例如“PROJ-123”）
• 状态：问题转换的目标状态（例如，“进行中”，“完成”）
• 评论：可选的注释，可在转换时添加

获取问题详情

获取有关 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，可选）：返回的最大用户数（默认值：10）
• include_active_users （bool，可选）：在搜索结果中包含活跃用户（默认值：True）
• include_inactive_users （bool，可选）：在搜索结果中包含非活动用户（默认值：False）

使用示例：

GDPR 合规性说明：

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

示例用法

发展

对于想要修改或扩展此 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 进行测试