@undefined0_0/jira-mcp

v0.0.12

Published

3 months ago

JIRA MCP Server - Ready to use MCP server for JIRA integration

0High
0Medium
0Low

undefined0_0

mcp jira

JIRA MCP Server

一个基于 Model Context Protocol (MCP) 的 JIRA 服务器，提供完整的 JIRA 问题管理功能。

版权声明

本项目基于 cosmix/jira-mcp（MIT License）二次开发，新增功能。原项目版权归 cosmix 所有。

功能特性

🔍 问题搜索: 支持 JQL 查询搜索 JIRA 问题
📋 问题管理: 创建、更新、查看 JIRA 问题
🔄 状态转换: 获取和执行问题状态转换
🏷️ 自定义字段: 支持部门、团队、需求范围等自定义字段
🔗 问题关联: 自动提取问题描述和评论中的关联问题

快速开始

安装

本工具需要在支持 MCP (Model Context Protocol) 的工具中使用，如 Claude Desktop、Cline 等。

方法一：使用 npx（推荐）

npx @undefined0_0/jira-mcp

方法二：本地安装

npm install -g @undefined0_0/jira-mcp

MCP 配置

在支持 MCP 的工具中配置 JIRA 服务器：

Claude Desktop 配置示例

{
  "mcpServers": {
    "jira-mcp": {
      "command": "npx",
      "args": ["@undefined0_0/jira-mcp"],
      "env": {
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your-username",
        "JIRA_TYPE": "server",
        "DEPARTMENT_FIELD": "customfield_10506",
        "TEAM_FIELD": "customfield_11863",
        "REQUIREMENT_SCOPE_FIELD": "customfield_14501",
        "ACCEPTANCE_CRITERIA_FIELD": "customfield_10555",
        "TEST_TYPE_FIELD": "customfield_15701",
        "STORY_POINTS_FIELD": "customfield_10006",
        "FUNCTION_POINTS_FIELD": "customfield_11875",
        "DEVELOPERS_FIELD": "customfield_11637",
        "USER_INTERFACE_FIELD": "customfield_13901",
        "PLANNED_COMPLETION_DATE_FIELD": "customfield_13632"
      }
    }
  }
}

API 工具

1. 搜索问题 (search_issues)

通过 JQL 查询搜索 JIRA 问题。

{
  "searchString": "project = PROJECT AND status = 'To Do'"
}

2. 获取问题详情 (get_issue)

获取指定问题的详细信息，包括评论。

{
  "issueId": "PROJECT-123"
}

3. 创建问题 (create_issues)

批量创建 JIRA 问题。

注意： 对于普通问题类型（如故事、任务、Bug 等），必填字段包括 projectKey、issueType、summary、requirementScope、description 和 acceptanceCriteria。而对于子任务类型，只有 projectKey、issueType 和 summary 是必填的，其他字段都是可选的。

{
  "issues": [
    {
      "projectKey": "PROJECT",
      "issueType": "故事",
      "summary": "实现新功能",
      "requirementScope": "核心功能",
      "description": "详细描述...",
      "acceptanceCriteria": "验收标准...",
      "department": "技术部",
      "team": ["前端组", "后端组"],
      "storyPoints": 8,
      "priority": "High",
      "assignee": "[email protected]"
    },
    {
      "projectKey": "PROJECT",
      "issueType": "子任务",
      "summary": "实现子功能",
      "parent": "PROJECT-123",
      "assignee": "[email protected]",
      "originalEstimate": "4h"
    }
  ]
}

4. 更新问题 (update_issue)

更新指定问题的字段。

{
  "issueKey": "PROJECT-123",
  "fields": {
    "summary": "更新的标题",
    "description": "更新的描述",
    "priority": "Medium"
  }
}

5. 获取状态转换 (get_transitions)

获取问题可执行的状态转换。

{
  "issueKey": "PROJECT-123"
}

6. 执行状态转换 (transition_issue)

执行问题状态转换。

{
  "issueKey": "PROJECT-123",
  "transitionId": "21",
  "comment": "状态转换说明"
}

自定义字段支持

支持以下自定义字段：

部门 (DEPARTMENT_FIELD): 问题所属部门
团队 (TEAM_FIELD): 问题负责团队
需求范围 (REQUIREMENT_SCOPE_FIELD): 需求范围分类
验收标准 (ACCEPTANCE_CRITERIA_FIELD): 验收标准
测试类型 (TEST_TYPE_FIELD): 测试类型
故事点数 (STORY_POINTS_FIELD): 故事点估算
功能点数 (FUNCTION_POINTS_FIELD): 功能点估算
开发人员 (DEVELOPERS_FIELD): 开发人员列表
用户界面 (USER_INTERFACE_FIELD): 是否包含用户界面
计划完成日期 (PLANNED_COMPLETION_DATE_FIELD): 计划完成日期

环境变量配置

基础配置

认证配置（以下两种方式二选一）

方式一：用户名和API令牌（传统方式）

| 变量名 | 必需 | 描述 | 示例 | | ---------------- | ---- | ------------------------ | ----------------------------------- | | JIRA_BASE_URL | ✅ | JIRA 实例 URL | https://your-domain.atlassian.net | | JIRA_USERNAME | ✅ | JIRA 用户名或邮箱 | [email protected] | | JIRA_API_TOKEN | ✅ | JIRA API 令牌 | your-api-token |

方式二：Basic Authentication（优先使用）

| 变量名 | 必需 | 描述 | 示例 | | ---------------- | ---- | ------------------------ | ----------------------------------- | | JIRA_BASE_URL | ✅ | JIRA 实例 URL | https://your-domain.atlassian.net | | JIRA_BASIC_AUTH| ✅ | Basic Authentication值 | base64(username:password) |

注意：
认证方式一和认证方式二可以选择其一配置，只需要确保至少有一种认证方式被正确配置。如果同时配置了两种方式，将优先使用方式二（JIRA_BASIC_AUTH）。
JIRA_BASIC_AUTH 的值可以是纯 base64 编码的 username:password，也兼容带有 Basic 前缀的格式。

其他配置

| 变量名 | 必需 | 描述 | 示例 | | ---------------- | ---- | ------------------------ | ----------------------------------- | | JIRA_TYPE | ❌ | JIRA 类型 (server/cloud) | server | | JIRA_LOG_DIR | ❌ | 日志文件目录路径 | /path/to/logs | | JIRA_LOG_LEVEL | ❌ | 日志级别 | INFO |

自定义字段配置

可以通过环境变量自定义字段 ID：

DEPARTMENT_FIELD=customfield_10506
TEAM_FIELD=customfield_11863
REQUIREMENT_SCOPE_FIELD=customfield_14501
ACCEPTANCE_CRITERIA_FIELD=customfield_10555
TEST_TYPE_FIELD=customfield_15701
STORY_POINTS_FIELD=customfield_10006
FUNCTION_POINTS_FIELD=customfield_11875
DEVELOPERS_FIELD=customfield_11637
USER_INTERFACE_FIELD=customfield_13901
PLANNED_COMPLETION_DATE_FIELD=customfield_13632

日志功能

日志配置

本工具支持详细的日志记录功能，可以通过环境变量配置：

日志目录 (`JIRA_LOG_DIR`)

作用: 指定日志文件的存储目录
格式: 绝对路径或相对路径
示例: /var/log/jira-mcp 或 ./logs

日志级别 (`JIRA_LOG_LEVEL`)

可选值: DEBUG, INFO, WARN, ERROR
默认值: INFO
说明: 控制日志的详细程度

日志文件格式

日志文件命名格式：jira-mcp-YYYY-MM-DD-HH-MM-SS.log

日志内容包含：

时间戳
日志级别
操作类型
详细数据
错误信息（如有）

日志类型

系统日志: 服务器启动、关闭、初始化等
工具调用日志: MCP 工具调用的详细信息
API 调用日志: JIRA API 请求和响应
错误日志: 异常和错误信息

使用示例

{
  "mcpServers": {
    "jira-mcp": {
      "command": "npx",
      "args": ["@undefined0_0/jira-mcp"],
      "env": {
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your-username",
        "JIRA_TYPE": "server",
        "JIRA_LOG_DIR": "/var/log/jira-mcp",
        "JIRA_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

使用示例

搜索待办问题

npx @undefined0_0/jira-mcp

然后调用 search_issues 工具：

{
  "searchString": "project = PROJECT AND status = 'To Do' ORDER BY priority DESC"
}

创建新故事

{
  "issues": [
    {
      "projectKey": "PROJECT",
      "issueType": "故事",
      "summary": "用户登录功能",
      "requirementScope": "用户管理",
      "description": "实现用户登录功能，包括用户名密码验证",
      "acceptanceCriteria": "1. 用户输入正确的用户名和密码可以登录\n2. 登录失败时显示错误信息\n3. 支持记住登录状态",
      "department": "技术部",
      "team": ["前端组"],
      "storyPoints": 5,
      "priority": "High",
      "assignee": "[email protected]"
    }
  ]
}

更新问题状态

{
  "issueKey": "PROJECT-123",
  "transitionId": "21",
  "comment": "开始开发"
}

错误处理

所有 API 调用都会返回详细的错误信息，包括：

参数验证错误
JIRA API 错误
网络连接错误
权限错误

系统要求

Node.js >= 18.0.0
支持 MCP (Model Context Protocol) 的工具
有效的 JIRA 实例和 API 访问权限

支持的 MCP 工具

Claude Desktop
Cline
VSCode Tree
其他支持 MCP 协议的 AI 工具

致谢

感谢 cosmix/jira-mcp 项目提供的优秀基础代码。

作者

undefined0_0

许可证

本项目基于 MIT License 开源。

本项目版权

原项目版权

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

JIRA MCP Server

版权声明

功能特性

快速开始

安装

方法一：使用 npx（推荐）

方法二：本地安装

MCP 配置

Claude Desktop 配置示例

API 工具

1. 搜索问题 (search_issues)

2. 获取问题详情 (get_issue)

3. 创建问题 (create_issues)

4. 更新问题 (update_issue)

5. 获取状态转换 (get_transitions)

6. 执行状态转换 (transition_issue)

自定义字段支持

环境变量配置

基础配置

认证配置（以下两种方式二选一）

方式一：用户名和API令牌（传统方式）

方式二：Basic Authentication（优先使用）

其他配置

自定义字段配置

日志功能

日志配置

日志目录 (JIRA_LOG_DIR)

日志级别 (JIRA_LOG_LEVEL)

日志文件格式

日志类型

使用示例

使用示例

搜索待办问题

创建新故事

更新问题状态

错误处理

系统要求

支持的 MCP 工具

致谢

作者

许可证

本项目版权

原项目版权

MIT License

日志目录 (`JIRA_LOG_DIR`)

日志级别 (`JIRA_LOG_LEVEL`)