AI导哈

JIRA自然语言交互服务器

一个为JIRA设计的模型上下文协议（MCP）服务器，支持通过自然语言与JIRA实例进行交互，包括查询用户进度、搜索故事、分析冲刺和跟踪团队速度。

  • by akworob
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 akworob/jira-mcp-server

使用说明

JIRA MCP服务器

JIRA的模型上下文协议（MCP）服务器，支持与JIRA实例的自然语言交互。通过对话式人工智能查询用户进度、搜索故事、分析冲刺和跟踪团队速度。

特性

核心工具

  1. jira_search_issues -使用灵活的过滤器搜索JIRA问题

    • JQL查询支持高级搜索
    • 按项目、受让人、状态、类型、冲刺筛选
    • 摘要和描述中的文本搜索
    • 基于日期的过滤
    • 分页支持

  2. jira_get_user_progress -获取全面的用户进度报告

    • 在指定时间段内完成的问题
    • 目前正在进行中的工作
    • 故事点已完成
    • 速度计算

  3. jira_get_project_info -获取项目信息和统计数据

    • 项目元数据和描述
    • 按状态和类型统计的问题数量
    • 近期活动总结
    • 完成率

  4. jira_get_sprint_info -获取冲刺信息和进度

    • 主动、封闭和未来冲刺
    • 每个sprint中的问题
    • Sprint目标和日期
    • 故事点追踪

  5. jira_get_team_velocity -计算团队速度指标

    • 短跑平均速度
    • Sprint完成率
    • 预测性容量规划
    • 速度趋势

安装

先决条件

  • Python 3.8或更高版本
  • 具有API访问权限的JIRA帐户
  • JIRA API令牌（创建于https://id.atlassian.com/manage/api-tokens)

步骤1：克隆和设置

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

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

步骤2：配置环境变量

复制示例环境文件并填写您的凭据：

cp .env.example .env

编辑 .env 使用您的JIRA证书：

JIRA_URL=https://yourcompany.atlassian.net
JIRA_EMAIL=your-email@company.com
JIRA_API_TOKEN=your-api-token-here

步骤2a：测试连接（可选但推荐）

验证您的JIRA连接：

python test_connection.py

这将在配置Claude Desktop之前检查您的凭据和API访问权限。

步骤3：配置Claude桌面

将JIRA MCP服务器添加到您的Claude Desktop配置中：

对于macOS： 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json 对于Windows： 编辑 %APPDATA%\Claude\claude_desktop_config.json 对于Linux： 编辑 ~/.config/claude/claude_desktop_config.json

添加此配置：

{
  "mcpServers": {
    "jira": {
      "command": "/absolute/path/to/jira-mcp-server/venv/bin/python",
      "args": ["/absolute/path/to/jira-mcp-server/jira_mcp.py"],
      "env": {
        "JIRA_URL": "https://yourcompany.atlassian.net",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

注： 对两者都使用绝对路径 command 和 args。如果您使用的是虚拟环境（推荐），请指向venv中的Python二进制文件。

步骤4:重新启动克劳德桌面

添加配置后，重新启动Claude Desktop以加载MCP服务器。

使用示例

配置后，您可以向Claude自然语言询问有关JIRA数据的问题：

用户进度查询

  • “约翰这周在做什么？”
  • “显示我过去30天完成的故事”
  • “我们的团队在这次冲刺中完成了多少个故事点？”
  • “目前正在进行什么sarah@company.com?"

项目和Sprint查询

  • “给我介绍一下ABC项目”
  • “移动团队的主动冲刺是什么？”
  • “显示最后5次冲刺的冲刺速度”
  • “XYZ项目中打开了多少个bug？”

问题搜索

  • “查找分配给我的所有高优先级错误”
  • “搜索当前冲刺中的故事”
  • “显示过去24小时内更新的问题”
  • “查找MOBILE项目中的所有史诗”

团队分析

  • “计算我们团队在上个季度的速度”
  • “我们的冲刺完成率是多少？”
  • “我们可以在下一个冲刺中承诺多少个故事点？”
  • “显示当前冲刺的消耗量”

高级用法

使用JQL查询

这 jira_search_issues 该工具支持完整的JQL语法：

"Search using JQL: project = ABC AND status = 'In Progress' AND assignee = currentUser()"

响应格式

所有工具都支持JSON和Markdown响应格式：

  • 标记语言 （默认）：对话的人类可读格式
  • JSON：用于进一步处理的结构化数据

分页

服务器自动处理大型结果集的分页：

  • 自动分页：用户进度、冲刺信息和速度查询会自动获取所有问题（不超过合理的限制）
  • 手动分页：为 jira_search_issues，使用偏移和限制参数：
    "Get the next 50 issues (offset: 50, limit: 50)"
  • 限制：为防止性能问题，自动分页仅限于：
    • 用户进度：500个已完成问题，200个正在进行中，200个待办事项
    • Sprint信息：每个Sprint 500个问题
    • 团队速度：每次冲刺500个问题

配置选项

自定义字段映射

服务器使用 customfield_10000 默认情况下为故事点。如果您的JIRA实例使用其他字段：

  1. 在JIRA中查找您的故事点字段ID
  2. 更新代码中的字段引用

API费率限制

服务器遵守JIRA的API速率限制。对于大批量操作，请考虑：

  • 使用分页
  • 缓存频繁访问的数据
  • 实现请求限制

故障排除

身份验证错误

  • 验证您的JIRA_URL没有尾随斜线
  • 确保您的API令牌有效且未过期
  • 检查您的电子邮件是否与您的JIRA帐户匹配

权限问题

  • 确保您的帐户对您正在查询的项目具有读取权限
  • 某些字段可能需要额外的权限

未找到字段

  • 自定义字段因JIRA实例而异
  • 检查实例的字段配置
  • 根据需要更新代码中的字段ID

连接超时

  • 检查您的互联网连接
  • 验证JIRA实例是否可访问
  • 考虑增加代码中的超时值

安全考虑

  1. API代币存储：从不将API令牌提交到版本控制
  2. 环境变量：使用安全方法管理环境变量
  3. 访问控制：服务器继承经过身份验证的用户的权限
  4. 数据隐私：注意JIRA数据中的敏感信息

扩展服务器

要添加新工具，请执行以下操作：

  1. 创建一个新的Pydantic模型用于输入验证
  2. 添加新 @mcp.tool 装饰功能
  3. 实现JIRA API交互
  4. 添加适当的错误处理
  5. 支持JSON和Markdown输出格式

示例结构：

@mcp.tool(name="jira_new_tool")
async def jira_new_tool(params: NewToolInput) -> str:
    """Tool description"""
    # Implementation here
    pass

API 参考

环境变量

变量 描述 必填
JIRA_URL 您的JIRA实例URL 是
JIRA_EMAIL 您的JIRA帐户电子邮件 是
JIRA_API_TOKEN 您的JIRA API令牌 是

刀具参数

每个工具都接受特定的参数。有关详细的参数信息，请使用Claude中的工具说明。

贡献

欢迎投稿！请随时提交拉取请求。对于重大更改，请先打开一个问题来讨论您想要更改的内容。

开发设置

  1. 分叉存储库
  2. 创建功能分支(git checkout -b feature/AmazingFeature)
  3. 进行更改
  4. 使用以下工具进行彻底测试 test_connection.py
  5. 提交您的更改(git commit -m 'Add some AmazingFeature')
  6. 推到分支(git push origin feature/AmazingFeature)
  7. 打开拉取请求

许可证

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

此MCP服务器按原样提供，供Claude和JIRA使用。确保遵守组织关于API使用和数据访问的政策。

支持

对于问题或疑问：

  1. 检查上面的故障排除部分
  2. 审查JIRA API文件
  3. 查阅MCP协议文档

技术细节

JIRA API版本

此服务器使用 JIRA REST API v3 (/rest/api/3/)，确保与最新Atlassian Cloud实例的兼容性。不支持不推荐使用的v2 API。

自动分页

服务器自动获取以下所有可用结果：

  • 用户进度查询（具有可配置的限制）
  • Sprint问题检索
  • 团队速度计算

即使JIRA的API限制为每页100个结果，这也能确保您获得完整的数据。

连接测试

使用随附的 test_connection.py 要验证的脚本：

  • 环境变量设置正确
  • JIRA凭据有效
  • API访问正在工作
  • 项目权限正确
  • 敏捷/Scrum功能可用

版本历史

  • v1.1.0版本 -增强的分页和API更新

    • 所有查询类型的自动分页
    • 迁移到JIRA API v3
    • 改进了错误处理
    • 连接测试脚本

  • v1.0.0 -带有核心JIRA工具的初始版本

    • 问题搜索和过滤
    • 用户进度跟踪
    • 项目信息
    • Sprint管理
    • 团队速度计算

相关 MCP