JIRA MCP 服务器

一个简单的 模型上下文协议 (MCP) "vibe-coded" 服务器，用于将 JIRA 与 Cursor IDE 集成。 MCP 是一个开放协议，可以实现 LLM 应用程序与外部数据源和工具之间的无缝集成。

此实现最初是通过丢弃另一个我们在 Cursor 中初始化失败的 JIRA MCP 服务器开始的。

注意！ 即使本文档也几乎完全由 AI 编码助手编写。

功能

• 通过 key 获取 JIRA issue
• 使用 JQL (JIRA 查询语言) 搜索 issue
• 创建和更新 issue (注意：对于高度定制的 JIRA 项目可能存在限制)
• 向 issue 添加评论
• 克隆 issue (对于解决强制性自定义字段很有用，但对于复杂的项目配置可能存在限制)
• 可配置的字段选择
• 分页支持
• 详细的错误处理和日志记录
• 记录工作时间

用户工作流程

搜索和过滤流程

graph LR
    A[开始搜索] -->|输入 JQL| B[搜索查询]
    B -->|应用过滤器| C[结果]
    C -->|选择字段| D[自定义视图]
    D -->|分页| E[更多结果]
    
    subgraph 搜索选项
        F[JQL 查询]
        G[字段选择]
        H[结果限制]
        I[起始位置]
    end
    
    B -->|使用| F
    C -->|使用| G
    C -->|使用| H
    C -->|使用| I

Issue 克隆流程

graph LR
    A[查找源 Issue] -->|复制 Key| B[克隆 Issue]
    B -->|自定义字段| C[修改后的克隆]
    C -->|创建| D[新 Issue]
    
    subgraph 克隆选项
        E[更改项目]
        F[修改字段]
        G[复制附件]
        H[添加源链接]
    end
    
    B -->|可以使用| E
    B -->|可以使用| F
    B -->|可以使用| G
    B -->|可以使用| H

有关详细的技术架构和系统工作流程，包括 issue 生命周期和身份验证流程，请参阅 ARCHITECTURE.md。

关于 MCP

该服务器实现了 模型上下文协议 规范，允许 Cursor IDE 通过其 AI 功能与 JIRA 数据无缝交互。 该协议标准化了 LLM 应用程序如何与外部数据源和工具通信。

设置

1. 创建一个虚拟环境:

python -m venv venv
source venv/bin/activate  # 在 Windows 上: venv\Scripts\activate

2. 安装依赖:

pip install -r requirements.txt

3. 配置环境变量: 创建一个 .env 文件，内容如下:

JIRA_URL=your_jira_url
JIRA_USERNAME=your_username
JIRA_API_TOKEN=your_api_token

使用

运行服务器:

./run-jira-mcp.sh

开发

该项目遵循 IMPLEMENTATION_PLAN.md 中概述的实施计划。

当前版本: v0.4

• ✅ 基本 JIRA 集成
• ✅ 具有 JQL 支持的搜索功能
• ✅ Issue 管理 (创建、更新、克隆)，但对于高度定制的项目存在限制
• ✅ 评论功能
• ✅ 工作时间记录

相关链接

• 模型上下文协议 - 主要的 MCP 项目
• MCP Python SDK - 我们用来实现此服务器的 SDK
• MCP 文档 - 协议文档和规范

许可证

MIT

安全注意事项

此工具主要用于个人工作流程自动化和个人开发者使用。 请注意以下安全注意事项：

⚠️ 使用建议

• 个人/开发用途: 适用于管理其 JIRA 工作流程的个人开发者
• 小型团队使用: 适用于具有适当安全措施的受信任团队环境
• 不推荐用于:
  • 当前形式的生产部署
  • 多租户环境
  • 面向公众的服务
  • 处理敏感/受监管的数据

🔒 安全要求

如果您选择使用此工具，请确保：

1. 您的 JIRA 实例使用 HTTPS
2. 您使用 API 令牌（而不是密码）进行身份验证
3. 您的 .env 文件已正确保护，并且未提交到版本控制
4. 您了解运行具有 JIRA 访问权限的第三方工具的风险

🛡️ 最佳实践

1. 定期轮换您的 API 令牌
2. 监控您的 JIRA 审计日志以查找意外活动
3. 使用该工具的最新版本
4. 在您的环境中使用之前，请查看代码

📝 关于企业使用的说明

该工具目前尚未针对企业安全要求进行强化。 如果您需要用于企业部署的解决方案，请考虑：

• 实施额外的安全控制
• 进行安全审查
• 将安全改进贡献回项目
• 使用官方的企业级替代方案

对于与安全相关的问题或报告漏洞，请打开一个 issue 或直接联系维护人员。