Jira-MCP

Name: Jira-MCP
Author: cosmix

作者：cosmix22 星标更新：2025-07-26

安装使用来源：spider==github.com

项目介绍

JIRA MCP 服务器

这是一个实现模型上下文协议（MCP）服务器，提供对 JIRA 数据的访问，包括关系跟踪、优化的数据负载以及用于 AI 上下文窗口的数据清理。

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

支持 Jira Cloud 和 Jira Server (数据中心)

此 MCP 服务器支持 Jira Cloud 和 Jira Server (数据中心) 实例。您可以通过设置 JIRA_TYPE 环境变量来选择要使用的类型：

cloud（默认）：适用于 Jira Cloud（由 Atlassian 托管）
server：适用于 Jira Server/数据中心（自托管）

服务器会自动使用所选类型的正确 API 版本和身份验证方法。

功能

使用 JQL 搜索 JIRA 问题（每个请求最多 50 条结果）
获取史诗子任务及其评论历史和优化的负载（每个请求最多 100 个问题）
获取详细的问题信息，包括评论和相关问题
创建、更新和管理 JIRA 问题
向问题添加评论
从 Atlassian 文档格式中提取问题提及
跟踪问题关系（提及、链接、父/子、史诗）
清理并转换丰富的 JIRA 内容以提高 AI 上下文效率
支持带有安全多部分上传处理的文件附件
同时支持 Jira Cloud 和 Jira Server (数据中心) 的 API

先决条件

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

环境变量

JIRA_API_TOKEN=your_api_token            # 云 API 令牌，或服务器/数据中心的 PAT 或密码
JIRA_BASE_URL=your_jira_instance_url     # 例如，https://your-domain.atlassian.net
JIRA_USER_EMAIL=your_email               # 您的 Jira 帐户电子邮件
JIRA_TYPE=cloud                          # 'cloud' 或 'server'（可选，默认为 'cloud'）
JIRA_AUTH_TYPE=basic                     # 'basic' 或 'bearer'（可选，默认为 'basic'）

身份验证方法

Jira Cloud：使用带有基本身份验证的 API 令牌
- 在 https://id.atlassian.com/manage-profile/security/api-tokens 创建一个 API 令牌
- 设置 JIRA_AUTH_TYPE=basic（默认值）
Jira Server/数据中心：
- 基本认证：使用用户名/密码或 API 令牌
  - 设置 JIRA_AUTH_TYPE=basic（默认值）
- Bearer 认证：使用个人访问令牌（PAT），在 8.14.0+ 版本的 Data Center 中可用
  - 在您的个人资料设置中创建一个 PAT
  - 设置 JIRA_AUTH_TYPE=bearer
  - 将 PAT 用作您的 JIRA_API_TOKEN

安装与设置

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",
        "JIRA_TYPE": "cloud",
        "JIRA_AUTH_TYPE": "basic"
      }
    }
  }
}

4. 重启 MCP 服务器

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

开发

运行测试：

bun test

开发监视模式：

bun run dev

更改后重新构建：

bun run build

可用的 MCP 工具

search_issues

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

输入模式：

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

get_epic_children

获取史诗中的所有子任务及其评论和关系数据。每个请求限制 100 个问题。

输入模式：

{
  epicKey: string; // 史诗问题的关键字
}

get_issue

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

输入模式：

{
  issueId: string; // JIRA 问题的 ID 或关键字
}

create_issue

创建具有指定字段的新 JIRA 问题。

输入模式：

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

update_issue

更新现有 JIRA 问题的字段。

输入模式：

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

add_attachment

向 JIRA 问题添加文件附件。

输入模式：

{
  issueKey: string, // 问题的关键字
  fileContent: string, // 基于64编码的文件内容
  filename: string // 要附加的文件名
}

add_comment

向 JIRA 问题添加评论。接受纯文本，并将其内部转换为所需的 Atlassian 文档格式。

输入模式：

{
  issueIdOrKey: string, // 要添加评论的问题的 ID 或关键字
  body: string // 评论的内容（纯文本）
}

数据清理功能

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

技术细节

使用 TypeScript 严格模式构建
使用 Bun 运行时以提高性能
使用 Vite 进行优化构建
使用 JIRA REST API v3（云）或 v2（服务器/数据中心）
支持多种身份验证方法：
- 使用 API 令牌或用户名/密码的基本认证
- 使用个人访问令牌（PAT）的 Bearer 认证
相关数据的批量 API 请求
为 AI 上下文窗口优化响应负载
复杂的 Atlassian 结构高效转换
强大的错误处理
考虑到速率限制
最大限制：
- 搜索结果：每个请求 50 个问题
- 史诗子任务：每个请求 100 个问题
支持多部分表单数据以安全地附加文件
自动内容类型检测和验证

错误处理

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

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

LICENSE

该项目根据 MIT 许可证发布 - 查看 LICENSE 文件以获取详细信息。