AI导哈

Jira查询服务器

一个用于查询Jira问题的Model Context Protocol (MCP)服务器，支持通过Jira问题Key查询详细信息、项目问题列表和自定义JQL查询，适用于开发者在Kiro IDE中快速获取Jira卡片信息。

  • by OneForCheng
  • JavaScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 OneForCheng/jira-query-mcp

使用说明

Jira Query MCP Server

一个用于查询 Jira 问题的 Model Context Protocol (MCP) 服务器，可以在 Kiro IDE 中直接查询 Jira 卡片信息。

功能特性

  • 通过 Jira 问题 Key 查询详细信息
  • 查询项目的所有问题和子任务列表
  • 支持 JQL 自定义查询过滤
  • 支持代理配置（可选）
  • 返回结构化的 Jira 问题数据，包括：
    • 基本信息（标题、描述、状态、负责人等）
    • 优先级和问题类型
    • 创建和更新时间
    • 标签和评论
    • 附件信息
    • 子任务信息

安装步骤

1. 克隆项目

git clone https://github.com/OneForCheng/jira-query-mcp.git
cd jira-query-mcp

2. 安装依赖

npm install

3. 配置 MCP 服务器

在 Kiro IDE 中配置 MCP 服务器，有两种配置方式：

方式一：用户级别配置（推荐）

编辑用户级别的 MCP 配置文件 ~/.kiro/settings/mcp.json：

{
  "mcpServers": {
    "jira-query": {
      "command": "node",
      "args": [
        "/path/to/your/jira-query-mcp/index.js"
      ],
      "cwd": "/path/to/your/jira-query-mcp",
      "env": {
        "NODE_TLS_REJECT_UNAUTHORIZED": "0",
        "JIRA_HOST": "https://your-jira-instance.com",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "JIRA_API_VERSION": "2",
        "PROXY_AGENT": "socks5h://127.0.0.1:1080"
      },
      "disabled": false,
      "autoApprove": [
        "get_jira_issue",
        "get_jira_issues"
      ]
    }
  }
}

方式二：工作区级别配置

在项目根目录创建 .kiro/settings/mcp.json：

{
  "mcpServers": {
    "jira-query": {
      "command": "node",
      "args": [
        "/path/to/your/jira-query-mcp/index.js"
      ],
      "cwd": "/path/to/your/jira-query-mcp",
      "env": {
        "NODE_TLS_REJECT_UNAUTHORIZED": "0",
        "JIRA_HOST": "https://your-jira-instance.com",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "JIRA_API_VERSION": "2",
        "PROXY_AGENT": "socks5h://127.0.0.1:1080"
      },
      "disabled": false,
      "autoApprove": [
        "get_jira_issue",
        "get_jira_issues"
      ]
    }
  }
}

环境变量配置

必需的环境变量

变量名 描述 示例
JIRA_HOST Jira 实例的 URL https://your-company.atlassian.net
JIRA_API_TOKEN Jira API Token your-api-token-here

可选的环境变量

变量名 描述 示例 默认值
JIRA_API_VERSION Jira REST API 版本 2 或 3 2
PROXY_AGENT 代理服务器地址 socks5h://127.0.0.1:1080 无（不使用代理）
NODE_TLS_REJECT_UNAUTHORIZED 是否验证 TLS 证书 0 或 1 1

获取 Jira API Token

  1. 登录到你的 Jira 实例
  2. 进入 用户信息 > 个人访问令牌
  3. 点击 创建令牌
  4. 输入 Token 名称并创建
  5. 复制生成的 Token（注意：Token 只显示一次）

代理配置说明

如果你的网络环境需要通过代理访问 Jira，可以设置 PROXY_AGENT 环境变量。本服务器支持多种代理协议：

SOCKS 代理

  • SOCKS5：socks5://127.0.0.1:1080
  • SOCKS5 with hostname resolution：socks5h://127.0.0.1:1080
  • SOCKS4：socks4://127.0.0.1:1080
  • 通用 SOCKS：socks://127.0.0.1:1080

HTTP/HTTPS 代理

  • HTTP 代理：http://proxy.company.com:8080
  • HTTPS 代理：https://proxy.company.com:8080
  • 带认证的代理：http://username:password@proxy.company.com:8080

代理配置示例

{
  "env": {
    "PROXY_AGENT": "socks5h://127.0.0.1:1080"
  }
}

或者使用 HTTP 代理：

{
  "env": {
    "PROXY_AGENT": "http://proxy.company.com:8080"
  }
}

如果不需要代理，可以不设置此环境变量或将其留空。

使用方法

配置完成后，在 Kiro IDE 中可以使用以下工具：

get_jira_issue

查询指定的 Jira 问题。

参数：

  • issueKey (string): Jira 问题的 Key，例如 "PROJ-123"

示例：

// 在 Kiro IDE 中使用
get_jira_issue({ issueKey: "PROJ-123" })

返回数据包含：

  • 问题基本信息（Key、标题、描述）
  • 状态和负责人
  • 优先级和问题类型
  • 时间信息（创建时间、更新时间）
  • 标签和评论列表
  • 附件信息（文件名、作者、创建时间、大小、MIME类型、下载链接）

get_jira_issues

查询项目的所有问题和子任务列表。

参数：

  • projectKey (string, 必需): 项目 Key，例如 "PP"、"PHOENIX"
  • jql (string, 可选): 自定义 JQL 查询条件，用于过滤问题

示例：

// 查询项目的所有问题
get_jira_issues({ projectKey: "PHOENIX" })

// 使用 JQL 过滤特定状态的问题
get_jira_issues({ 
  projectKey: "PHOENIX", 
  jql: "status = '待办'" 
})

// 查询指定负责人的问题
get_jira_issues({ 
  projectKey: "PHOENIX", 
  jql: "assignee = 'cheng'" 
})

// 组合多个条件
get_jira_issues({ 
  projectKey: "PHOENIX", 
  jql: "status = '待办' AND priority = 'High'" 
})

返回数据包含：

  • 分页信息（total、startAt、maxResults）
  • 问题列表，每个问题包含：
    • 基本信息（Key、ID、标题、描述）
    • 状态、负责人、报告人
    • 优先级和问题类型
    • 时间信息（创建时间、更新时间、截止日期）
    • 标签
    • 子任务列表（Key、标题、状态）

故障排除

常见问题

  1. 连接超时或无法访问 Jira

    • 检查 JIRA_HOST 是否正确
    • 如果在公司网络环境，确认是否需要配置代理

  2. 认证失败

    • 验证 JIRA_API_TOKEN 是否正确
    • 确认 Token 是否已过期

  3. TLS/SSL 证书错误

    • 设置 NODE_TLS_REJECT_UNAUTHORIZED=0 来跳过证书验证（仅用于开发环境）

  4. MCP 服务器无法启动

    • 检查 Node.js 版本是否兼容
    • 确认项目路径是否正确
    • 查看 Kiro IDE 的 MCP 服务器日志

调试模式

如需调试，可以在环境变量中添加：

{
  "env": {
    "DEBUG": "mcp:*",
    "FASTMCP_LOG_LEVEL": "DEBUG"
  }
}

项目结构

jira-query-mcp/
├── index.js           # MCP 服务器主文件
├── package.json       # 项目依赖配置
├── package-lock.json  # 依赖锁定文件
└── README.md         # 本文档

依赖项

  • @modelcontextprotocol/sdk - MCP SDK
  • node-fetch - HTTP 请求库
  • socks-proxy-agent - SOCKS 代理支持
  • https-proxy-agent - HTTP/HTTPS 代理支持

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！

更新日志

v1.1.0

  • 新增 get_jira_issues 工具，支持查询项目的所有问题和子任务
  • 支持 JQL 自定义查询过滤
  • 返回数据包含子任务信息

v1.0.0

  • 初始版本
  • 支持基本的 Jira 问题查询
  • 支持多种代理协议（SOCKS4/5、HTTP/HTTPS）
  • 智能代理协议检测
  • 环境变量配置支持

相关 MCP