JIRA MCP 服务器

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

这个实现最初是通过放弃另一个我们无法在 Cursor 中初始化的 JIRA MCP 服务器开始的。

请注意！即使这份文档也几乎完全是由 AI 编码助手编写的。

功能

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

用户工作流程

搜索和过滤流程

graph LR
    A[Start Search] -->|Enter JQL| B[Search Query]
    B -->|Apply Filters| C[Results]
    C -->|Select Fields| D[Customized View]
    D -->|Pagination| E[More Results]
    
    subgraph Search Options
        F[JQL Query]
        G[Field Selection]
        H[Result Limit]
        I[Start Position]
    end
    
    B -->|Uses| F
    C -->|Uses| G
    C -->|Uses| H
    C -->|Uses| I

问题克隆流程

graph LR
    A[Find Source Issue] -->|Copy Key| B[Clone Issue]
    B -->|Customize Fields| C[Modified Clone]
    C -->|Create| D[New Issue]
    
    subgraph Clone Options
        E[Change Project]
        F[Modify Fields]
        G[Copy Attachments]
        H[Add Source Link]
    end
    
    B -->|Can Use| E
    B -->|Can Use| F
    B -->|Can Use| G
    B -->|Can Use| H

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

关于 MCP

该服务器实现了 Model Context Protocol 规范，允许 Cursor IDE 通过其 AI 功能无缝地与 JIRA 数据交互。该协议标准化了 LLM 应用程序与外部数据源和工具之间的通信方式。

设置

1. 创建虚拟环境：

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

1. 安装依赖项：

pip install -r requirements.txt

1. 配置环境变量：
   创建一个 .env 文件，并包含以下内容：

JIRA_URL=your_jira_url
JIRA_USERNAME=your_username
JIRA_API_TOKEN=your_api_token

使用

运行服务器：

./run-jira-mcp.sh

开发

该项目遵循模块化结构：

src/
├── core/           # Core JIRA client implementation
│   ├── __init__.py
│   ├── client.py   # JiraClient class
│   └── config.py   # Configuration management
├── models/         # Pydantic models for validation
│   ├── __init__.py
│   ├── comment.py  # Comment-related models
│   ├── issue.py    # Issue-related models
│   └── worklog.py  # Worklog-related models
└── operations/     # MCP operation implementations
    ├── __init__.py
    ├── comments.py # Comment operations
    ├── issues.py   # Issue operations
    ├── projects.py # Project operations
    └── worklog.py  # Worklog operations

主要组件

1. 模型 (src/models/)

   • IssueType, IssueArgs - 问题创建/更新模型
   • IssueTransitionArgs - 问题状态转换模型
   • CloneIssueArgs - 问题克隆模型
   • CommentArgs, GetCommentsArgs - 评论模型
   • LogWorkArgs - 工作记录模型

2. 核心 (src/core/)

   • JiraClient - 主 JIRA API 客户端
   • JiraConfig - 配置管理
   • 错误处理和日志记录

3. 操作 (src/operations/)

   • 问题管理（获取、搜索、创建、更新、克隆）
   • 评论处理（添加、获取）
   • 工作记录
   • 项目列表

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

当前版本：v0.4

• ✅ 基本 JIRA 集成
• ✅ 支持 JQL 的搜索功能
• ✅ 问题管理（创建、更新、克隆），对于高度定制化的项目存在限制
• ✅ 评论功能
• ✅ 工作记录

相关链接

• Model Context Protocol - 主 MCP 项目
• MCP Python SDK - 我们用来实现此服务器的 SDK
• MCP 文档 - 协议文档和规范

许可证

MIT

安全考虑

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

⚠️ 使用建议

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

🔒 安全要求

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

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

🛡️ 最佳实践

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

📝 关于企业用途的说明

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

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

对于与安全相关的疑虑或报告漏洞，请打开一个issue或直接联系维护者。