JIRA MCP 服务器

一个模型上下文协议 (MCP) 服务器实现，提供对 JIRA 数据的访问，具有关系跟踪、优化的数据负载以及用于 AI 上下文窗口的数据清理功能。

ℹ️ 还有一个单独的 Confluence 的 MCP 服务器

功能

• 使用 JQL 搜索 JIRA 问题（每个请求最多 50 个结果）
• 检索 Epic 的子问题，包含评论历史和优化的数据负载（每个请求最多 100 个问题）
• 获取详细的问题信息，包括评论和相关问题
• 创建、更新和管理 JIRA 问题
• 从 Atlassian 文档格式中提取问题提及
• 跟踪问题关系（提及、链接、父/子、Epic）
• 清理和转换丰富的 JIRA 内容，以提高 AI 上下文效率
• 支持文件附件，具有安全的多部分上传处理

前提条件

• Bun (v1.0.0 或更高版本)
• 具有 API 访问权限的 JIRA 帐户

环境变量

JIRA_API_TOKEN=your_api_token
JIRA_BASE_URL=your_jira_instance_url  # 例如，https://your-domain.atlassian.net
JIRA_USER_EMAIL=your_email

安装与设置

1. 克隆存储库：

git clone [repository-url]
cd jira-mcp

2. 安装依赖项并构建：

bun install
bun run build

3. 配置 MCP 服务器：

编辑相应的配置文件：

macOS:

• Cline: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

• Cline: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
• Claude Desktop: %APPDATA%\Claude Desktop\claude_desktop_config.json

Linux:

• Cline: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Claude Desktop: 很遗憾，目前还没有

在 mcpServers 对象下添加以下配置：

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/jira-mcp/build/index.js"],
      "env": {
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_BASE_URL": "your_jira_instance_url",
        "JIRA_USER_EMAIL": "your_email"
      }
    }
  }
}

4. 重启 MCP 服务器。

在 Cline 的 MCP 设置中，重启 MCP 服务器。重启 Claude Desktop 以加载新的 MCP 服务器。

开发

运行测试：

bun test

开发模式下的监听：

bun run dev

更改后重新构建：

bun run build

可用的 MCP 工具

search_issues

使用 JQL 搜索 JIRA 问题。每个请求最多返回 50 个结果。

输入 Schema:

{
  searchString: string // JQL 搜索字符串
}

get_epic_children

获取 Epic 中的所有子问题，包括它们的评论和关系数据。每个请求限制为 100 个问题。

输入 Schema:

{
  epicKey: string // Epic 问题的 Key
}

get_issue

获取有关特定 JIRA 问题的详细信息，包括评论和所有关系。

输入 Schema:

{
  issueId: string // JIRA 问题的 ID 或 Key
}

create_issue

使用指定的字段创建一个新的 JIRA 问题。

输入 Schema:

{
  projectKey: string, // 将创建问题的项目 Key
  issueType: string, // 问题的类型（例如，“Bug”、“Story”、“Task”）
  summary: string, // 问题摘要/标题
  description?: string, // 可选的问题描述
  fields?: { // 可选的附加字段
    [key: string]: any
  }
}

update_issue

更新现有 JIRA 问题的字段。

输入 Schema:

{
  issueKey: string, // 要更新的问题的 Key
  fields: { // 要更新的字段
    [key: string]: any
  }
}

add_attachment

将文件附件添加到 JIRA 问题。

输入 Schema:

{
  issueKey: string, // 问题的 Key
  fileContent: string, // Base64 编码的文件内容
  filename: string // 要附加的文件名
}

数据清理功能

• 从 Atlassian 文档格式中提取文本
• 跟踪描述和评论中的问题提及
• 维护具有关系类型的正式问题链接
• 保留父/子关系
• 跟踪 Epic 关联
• 包括带有作者信息的评论历史
• 从响应中删除不必要的元数据
• 递归处理内容节点以进行提及
• 删除重复的问题提及

技术细节

• 使用 TypeScript 以严格模式构建
• 使用 Bun 运行时以提高性能
• Vite 用于优化构建
• 使用 JIRA REST API v3
• 使用 API 令牌进行基本身份验证
• 批量 API 请求以获取相关数据
• 针对 AI 上下文窗口优化的响应负载
• 高效转换复杂的 Atlassian 结构
• 强大的错误处理
• 速率限制注意事项
• 最大限制：
  • 搜索结果：每个请求 50 个问题
  • Epic 子问题：每个请求 100 个问题
• 支持多部分表单数据以实现安全的文件附件
• 自动内容类型检测和验证

错误处理

服务器实现了全面的错误处理策略：

• 网络错误检测和适当的消息传递
• HTTP 状态代码处理（尤其是问题的 404）
• 带有状态代码的详细错误消息
• 将错误详细信息记录到控制台
• 所有参数的输入验证
• 通过 MCP 协议进行安全错误传播
• 专门处理常见的 JIRA API 错误
• 附件的 Base64 验证
• 多部分请求失败处理
• 速率限制检测
• 附件参数验证

许可证

本项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENCE 文件。