MCP Jira 集成

一个简单的 Jira 模型上下文协议 (MCP) 服务器，允许 LLM 为使用 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 状态和问题类型

Related MCP server: JIRA MCP Server

要求

• 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
JIRA_USERNAME=your.email@domain.com
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 停止。

使用示例

创建问题

"Create a high priority bug for the login system not working properly"

• 自动分配正确的问题类型、优先级和格式

冲刺管理

"What's our current sprint status?"

• 获取包含指标和视觉指示器的全面进度报告

团队管理

"Show me the team workload for john.doe, jane.smith, mike.wilson"

• 分析容量并提供工作量分配

每日站会

"Generate today's standup report"

• 创建包含已完成、进行中和阻塞事项的格式化报告

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 文档格式 (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. 提交 Pull Request

许可证

MIT 许可证 - 参见 LICENSE 文件