MCP Jira Integration

MCP Jira 集成

一个简单的 Jira 模型上下文协议（MCP）服务，可让大模型充当项目经理和个人助手，服务于使用 Jira 的团队。基于 Jira REST API v3 构建。

功能

核心 MCP 工具

• create_issue - 创建格式规范且采用 ADF 描述的新 Jira 问题
• search_issues - 使用 JQL 搜索问题，支持智能格式化和分页
• get_sprint_status - 获取包含指标的全面冲刺进度报告
• get_team_workload - 分析团队成员的工作负载和容量
• generate_standup_report - 自动生成每日站会报告

项目管理能力

• 多项目支持：通过动态指定项目键处理多个项目
• 带可视化指标的冲刺进度跟踪
• 团队工作负载分析和容量规划
• 自动生成每日站会报告
• 按规范优先级创建问题
• 智能搜索和筛选问题

可靠性

• 遇到速率限制（429）和瞬时错误（503）时，自动采用指数退避重试
• 为大型结果集提供分页
• 时区感知的日期处理
• 妥善处理自定义 Jira 状态和问题类型

要求

• Python 3.8 或更高版本
• 带 API 令牌的 Jira Cloud 账户
• 兼容 MCP 的客户端（如 Claude Desktop）

快速设置

1. 克隆并安装：

git clone https://github.com/your-org/mcp-jira.git
cd mcp-jira
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

2. 配置 Jira 凭据：

cp .env.example .env
# Edit .env with your values

JIRA_URL=https://your-domain.atlassian.net
[email protected]
JIRA_API_TOKEN=your_api_token
PROJECT_KEY=PROJ
DEFAULT_BOARD_ID=123

3. 测试服务：

.venv/bin/python -m mcp_jira

你应该会在输出中看到 Initializing MCP Jira server...。按 Ctrl+C 停止。

使用示例

创建问题

“为登录系统无法正常工作创建一个高优先级 Bug”

• 自动分配合适的问题类型、优先级并设置格式

冲刺管理

“我们当前的冲刺状态如何？”

• 获取包含指标和可视化指标的全面进度报告

团队管理

“显示 john.doe、jane.smith、mike.wilson 的团队工作负载”

• 分析容量并提供工作负载分布

每日站会

“生成今天的站会报告”

• 创建格式化报告，列出已完成、进行中和受阻事项

MCP 集成

与 Claude Desktop 配合使用

配置文件位于：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

添加以下条目，并将 /path/to/mcp-jira 替换为克隆仓库所在的绝对路径：

{
  "mcpServers": {
    "mcp-jira": {
      "command": "/path/to/mcp-jira/.venv/bin/python",
      "args": ["-m", "mcp_jira"]
    }
  }
}

注意：使用 .venv 文件夹中的 Python 二进制文件，以确保所有依赖项都可用。无需设置 cwd 字段；服务会在内部使用绝对路径解析配置。

要查找正确的路径，请在项目目录中运行：

echo "$(pwd)/.venv/bin/python"

保存配置后，重启 Claude Desktop。

与其他 MCP 客户端配合使用

该服务遵循标准 MCP 协议，可与任何兼容 MCP 的客户端配合使用。

配置

必需的环境变量

• JIRA_URL - Jira 实例 URL
• JIRA_USERNAME - Jira 用户名/电子邮件
• JIRA_API_TOKEN - Jira API 令牌
• PROJECT_KEY - 操作的默认项目键（可按请求覆盖）

可选设置

• DEFAULT_BOARD_ID - 冲刺操作的默认看板（可按请求覆盖）
• STORY_POINTS_FIELD - 故事点的自定义字段 ID（默认值：customfield_10026）
• DEBUG_MODE - 启用调试日志（默认值：false）
• LOG_LEVEL - 日志级别（默认值：INFO）

获取 Jira API 令牌

1. 前往 Atlassian 账户设置
2. 点击“Create API token”
3. 为令牌命名并复制令牌
4. 使用你的电子邮件作为用户名，并将令牌用作密码

架构

此实现优先考虑简洁性和可靠性：

• 单个 MCP 服务文件 - 所有工具都集中在一处
• 标准 MCP 协议 - 使用官方 MCP SDK
• Jira REST API v3 - 使用 Atlassian Document Format（ADF）编写描述
• 丰富的格式 - 提供美观易读的报告
• 退避重试 - 自动处理速率限制和 Jira API 临时错误
• 分页 - 获取大型问题集中的所有结果
• 错误处理 - 妥善处理 Jira API 问题和自定义状态
• 异步支持 - 操作快速且响应灵敏

故障排除

常见问题

1. “No active sprint found”

   • 确保你的看板有一个进行中的迭代
   • 检查 DEFAULT_BOARD_ID 是否设置正确

2. 身份验证错误

   • 确认 API 令牌正确
   • 检查用户名是否为你的电子邮件地址

3. 权限错误

   • 确保你的 Jira 用户拥有相应的项目权限
   • 检查项目键是否存在，以及你是否有权访问

调试模式

在 .env 文件中设置 DEBUG_MODE=true，以启用详细日志记录。

开发

1. Fork 此仓库
2. 设置开发环境：

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

3. 运行测试：

python -m pytest tests/ -v

4. 提交拉取请求

许可证

MIT 许可证 - 参见 LICENSE 文件