AI导哈

JIRA API工具

一个通过Claude Desktop与JIRA API交互的模型上下文协议工具，支持问题搜索、创建、更新、删除、评论和状态转换等功能。

  • by NZenitram
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 nzenitram/mcp-jira

使用说明

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. 点击“创建”并安全保存生成的令牌

GDPR合规性

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

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

故障排除

常见问题和解决方案：

  1. ModuleNotFoundation错误：没有名为“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. 点击“创建”并安全保存生成的令牌

工具

搜索问题

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

参数：

  • jjl:JIRA查询语言字符串（例如，“项目=演示和状态=打开”）
  • max_results：返回的最大结果数（默认值：10）
  • 字段：结果中包含的逗号分隔的字段列表（默认值：“摘要、状态、受让人、优先级、问题类型”）

创建问题

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

参数：

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

更新问题

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

参数：

  • issue_key：JIRA问题密钥（例如“PROJ-123”）
  • summary：问题的新摘要（可选）
  • description:问题的新描述（可选）
  • status：问题的新状态（可选，例如“进行中”、“完成”）
  • 优先级：问题的新优先级（可选，例如“高”、“中”、“低”）
  • 受让人：发行的新受让人（可选）
  • 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”）
  • 状态：将问题转换为的目标状态（例如，“进行中”、“完成”）
  • 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，可选）：返回的最大用户数（默认值：10）
  • include_active_users （bool，可选）：在搜索结果中包含活动用户（默认值：True）
  • include_inactive_users （bool，可选）：在搜索结果中包含非活动用户（默认值：False）

示例用法：

# Search for users with "john" in their display name or email
search_users(query="john")

# Search for up to 20 users, including inactive ones
search_users(
    query="smith",
    max_results=20,
    include_inactive_users=True
)

GDPR合规说明：

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

示例用法

Search for bugs in the PROJECT with high priority:
search_issues(jql="project=PROJECT AND issuetype=Bug AND priority=High")

Create a new bug in the PROJECT:
create_issue(project_key="PROJECT", summary="Login button not working", description="Users cannot log in using the login button on the homepage", issue_type="Bug", priority="High")

Update an existing issue:
update_issue(issue_key="PROJECT-123", summary="Updated: Login button fixed", status="In Progress", comment="Fixed the CSS styling issue")

Delete an issue:
delete_issue(issue_key="PROJECT-123", confirm=True)

List the first 5 projects:
list_projects(limit=5)

Add a comment to an issue:
add_comment(issue_key="PROJECT-123", comment="The fix has been deployed to production")

Transition an issue:
transition_issue(issue_key="PROJECT-123", status="In Progress", comment="Starting work on this issue")

Get issue details:
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进行测试

相关 MCP