@neosamon/jira-mcp-server

v0.3.0

Published

18 days ago

Jira MCP Server - Model Context Protocol server for Jira integration

0High
0Medium
0Low

neosamon

mcp jira model-context-protocol

Jira MCP Server

一个基于 TypeScript/Node.js 的 Jira Model Context Protocol (MCP) Server，允许 AI 助手直接与 Jira 进行交互。

架构

本项目采用分层模块化架构，将业务逻辑拆分为职责清晰的多个模块：

Domain Layer: 领域类型和错误定义
Infrastructure Layer: 配置管理和 HTTP 客户端
Service Layer: Jira API 客户端和数据格式化
Tool Layer: MCP 工具实现
Application Layer: 依赖注入和应用启动

详细的架构说明请参阅 ARCHITECTURE.md。

功能

查询 Issue: 通过 Issue Key 获取 Issue 的详细信息，包括类型、状态、优先级、描述和评论
搜索 Issues: 使用 JQL (Jira Query Language) 批量搜索 Issues
创建评论: 为指定的 Issue 添加评论
上传附件: 支持批量上传文件到 Issue（Base64 编码或本地文件路径）
下载附件: 从 Jira Issue 下载附件到本地文件系统
字段发现: 探测 Issue 的所有可用字段，用于配置自定义字段映射
自定义字段: 支持通过环境变量配置，提取 Jira 自定义字段

环境变量配置

在使用之前，需要设置以下环境变量：

| 环境变量 | 必需 | 说明 | 示例 | |----------|------|------|------| | JIRA_BASE_URL | 是 | Jira 服务器地址（不要以斜杠结尾） | https://your-jira.example.com | | JIRA_USERNAME | 是 | Jira 用户名或邮箱 | [email protected] | | JIRA_API_TOKEN | 条件必需* | Jira API Token | your-api-token-here | | JIRA_PASSWORD | 条件必需* | Jira 密码 | your-password | | JIRA_AUTH_TYPE | 否 | 认证方式：auto（默认）、token、password | auto | | JIRA_MAX_ATTACHMENT_SIZE | 否 | 附件大小限制（字节），默认 10MB | 10485760 | | JIRA_DOWNLOAD_PATH | 否 | 附件下载目录路径，默认 /tmp/ | /downloads | | LOG_LEVEL | 否 | 日志级别：trace、debug、info（默认）、warn、error | info | | LOG_TO_STDERR | 否 | 是否输出到 stderr，默认 true | true | | LOG_TO_FILE | 否 | 是否输出到文件，默认 false | false | | LOG_FILE_PATH | 否 | 日志文件路径，默认 /tmp/jira-mcp.log | /var/log/jira-mcp.log | | LOG_FILE_MAX_SIZE | 否 | 单文件最大大小，默认 10M | 10M | | LOG_FILE_MAX_FILES | 否 | 保留文件数量，默认 5 | 5 |

至少需要设置 JIRA_API_TOKEN 或 JIRA_PASSWORD 之一

认证方式说明

本 MCP Server 支持两种认证方式：

API Token 认证（推荐）: 更安全，可以随时撤销
密码认证: 适用于不支持 API Token 的旧版本 Jira

认证方式选择逻辑

JIRA_AUTH_TYPE 环境变量
│
├─ "token" → 强制使用 API Token（忽略 JIRA_PASSWORD）
├─ "password" → 强制使用密码（忽略 JIRA_API_TOKEN）
└─ "auto" 或未设置
   │
   ├─ 如果设置了 JIRA_PASSWORD → 使用密码（优先）
   └─ 否则 → 使用 API Token

获取 Jira API Token

登录到您的 Jira 实例
进入 Account Settings > Security > API Tokens
点击 Create API token
复制生成的 Token 并设置为 JIRA_API_TOKEN 环境变量

日志配置（可选）

本 MCP Server 支持结构化日志输出，便于调试和问题追踪。

日志级别

支持的日志级别（从详细到简略）：

trace: 最详细的日志，包含所有操作细节
debug: 调试信息，包括请求/响应详情
info: 一般信息（默认级别），包括 API 调用摘要
warn: 警告信息，包括重试和错误
error: 错误信息，仅记录失败的操作

输出目标

日志可以同时输出到 stderr 和文件：

stderr: 默认开启，适合开发调试，不会干扰 MCP 协议通信
文件: 需要手动启用，适合生产环境日志持久化

配置示例

仅 stderr（默认，开发环境推荐）:

export LOG_LEVEL="debug"  # 显示调试信息

启用文件日志（生产环境）:

export LOG_TO_FILE="true"
export LOG_FILE_PATH="/var/log/jira-mcp.log"
export LOG_FILE_MAX_SIZE="50M"
export LOG_FILE_MAX_FILES="10"

同时输出到 stderr 和文件:

export LOG_TO_STDERR="true"
export LOG_TO_FILE="true"
export LOG_FILE_PATH="/var/log/jira-mcp.log"

日志格式

日志采用 JSON 格式输出，便于解析和分析：

{
  "level": "info",
  "message": "Jira MCP Server 配置加载成功",
  "baseURL": "https://jira.example.com",
  "authType": "token",
  "timestamp": "2026-02-27T10:30:00.000Z"
}

日志文件轮转

当启用文件日志时，日志会自动轮转：

单个文件达到最大大小时自动创建新文件
旧文件会按时间戳命名并添加后缀（如 .1, .2）
超过保留数量的旧文件会自动删除

例如，配置 maxSize=10M 和 maxFiles=5 时：

jira-mcp.log        # 当前日志文件
jira-mcp.log.1      # 第一个轮转文件
jira-mcp.log.2      # 第二个轮转文件
...

自定义字段配置（可选）

Jira 实例通常包含自定义字段（如测试步骤、预期结果、代码分支等）。要提取这些字段，需要配置字段映射。

配置步骤

使用字段发现工具找出目标字段的 ID：

"使用 get_issue_fields 工具查看 Issue PROJ-123 的所有字段"

配置环境变量将字段名映射到字段 ID：

export JIRA_FIELD_TEST_STEP="customfield_10206"
export JIRA_FIELD_EXPECTED_RESULT="customfield_10208"
export JIRA_FIELD_ACTUAL_RESULT="customfield_10210"
export JIRA_FIELD_CODE_BRANCH="customfield_10300"

重启服务器，get_issue 工具将自动包含配置的自定义字段

字段映射规则

环境变量格式：JIRA_FIELD_<NAME>=<field_id>
字段名会自动转换为驼峰命名（如 JIRA_FIELD_TEST_STEP → testStep）
未配置的字段不会出现在输出中
字段不存在或为空时显示 N/A

安装

通过 npm 全局安装

npm install -g @neosamon/jira-mcp-server

使用 npx 运行（无需安装）

npx @neosamon/jira-mcp-server

使用方法

设置环境变量

使用 API Token 认证（推荐）

export JIRA_BASE_URL="https://your-jira.example.com"
export JIRA_USERNAME="[email protected]"
export JIRA_API_TOKEN="your-api-token"

npx @neosamon/jira-mcp-server

使用密码认证

export JIRA_BASE_URL="https://your-jira.example.com"
export JIRA_USERNAME="[email protected]"
export JIRA_PASSWORD="your-password"

npx @neosamon/jira-mcp-server

显式指定认证方式

# 强制使用 Token 认证
export JIRA_AUTH_TYPE="token"
export JIRA_API_TOKEN="your-api-token"

# 强制使用密码认证
export JIRA_AUTH_TYPE="password"
export JIRA_PASSWORD="your-password"

Claude Desktop 配置

在 Claude Desktop 的配置文件中添加以下内容：

macOS

配置文件路径: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows

配置文件路径: %APPDATA%\Claude\claude_desktop_config.json

配置内容

使用 API Token 认证（推荐）

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["@neosamon/jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-jira.example.com",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

使用密码认证

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["@neosamon/jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-jira.example.com",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_PASSWORD": "your-password"
      }
    }
  }
}

Claude CLI 配置

基于项目添加

claude mcp add jira --transport stdio \
    --env JIRA_BASE_URL="https://your-jira.example.com" \
    --env JIRA_USERNAME="[email protected]" \
    --env JIRA_PASSWORD="your-password" \
    -- npx @neosamon/jira-mcp-server

全局添加

claude mcp add jira --scope user --transport stdio \
    --env JIRA_BASE_URL="https://your-jira.example.com" \
    --env JIRA_USERNAME="[email protected]" \
    --env JIRA_PASSWORD="your-password" \
    -- npx @neosamon/jira-mcp-server

使用示例

配置完成后，您可以在 Claude 中使用以下命令：

基本功能

"查询 Jira Issue PROJ-123 的详情"
"为 PROJ-123 添加评论：已完成代码审查"
"上传文件 error.log 到 Issue PROJ-123"
"批量上传多个文件到 PROJ-456：screenshot.png、log.txt 和 report.pdf"

字段发现

"使用 get_issue_fields 工具查看 Issue PROJ-123 的所有可用字段"
"列出 PROJ-123 的字段，帮我找出测试步骤对应的字段 ID"

JQL 搜索

"搜索分配给我的所有进行中任务"
"查找项目 PROJ 中所有高优先级的 Bug"
"列出本周创建的所有 Issues"
"搜索状态为 Open 且优先级为 High 的 Issues"

附件上传

本 MCP Server 支持批量上传附件到 Jira Issue。

支持的输入方式

Base64 编码内容（适合小文件）
- AI 助手可以直接编码文件内容并上传
- 适合文本文件、JSON、小图片等
本地文件路径（适合大文件）
- 适用于 MCP Server 有文件系统访问权限的场景
- 适合大文件（如日志、压缩包）

附件大小限制

默认最大附件大小为 10MB。可通过环境变量 JIRA_MAX_ATTACHMENT_SIZE 配置：

export JIRA_MAX_ATTACHMENT_SIZE=20971520  # 20MB

使用示例

上传单个文件（Base64）:

上传 error.log 文件到 Issue PROJ-123

批量上传多个文件:

批量上传以下文件到 PROJ-456：
- screenshot.png
- error.log
- report.pdf

指定 MIME 类型:

对于常见文件类型，AI 助手会自动识别 MIME 类型
支持的类型包括：text/plain、application/json、image/png、image/jpeg、application/pdf 等

错误处理

附件上传具有完善的错误处理：

文件过大：会明确提示超出限制的文件及其大小
部分失败：会显示成功和失败的详细列表
格式错误：会提示具体的问题文件

示例输出：

📎 附件上传完成 - PROJ-123

📊 汇总: 2/3 成功

✅ 成功上传:
  • screenshot.png (150.50 KB)
    ID: att-100
  • error.log (5.20 KB)
    ID: att-101

❌ 失败:
  • huge.zip: File 'huge.zip' (15.00 MB) exceeds maximum size (10.00 MB)

附件下载

本 MCP Server 支持从 Jira Issue 下载附件到本地文件系统。

下载方式

使用 get_issue 工具获取 Issue 详情后，可以从返回的附件列表中获取附件 URL，然后使用 download_attachment 工具下载。

保存路径优先级

附件保存目录按以下优先级确定：

工具参数 outputPath: 最高优先级，允许临时覆盖默认路径
环境变量 JIRA_DOWNLOAD_PATH: 项目级默认配置
/tmp/ 目录: 通用回退选项

文件命名规则

下载的文件使用 {attachmentId}-{filename} 格式命名，防止不同附件的相同文件名冲突：

URL: http://jira.example.com/secure/attachment/151194/README.md
保存为: 151194-README.md

使用示例

从 Issue 获取附件 URL 并下载:

1. 查询 Issue PROJ-123 的详情，获取附件列表
2. 下载附件 /secure/attachment/151194/screenshot.png

指定自定义下载路径:

下载附件 /secure/attachment/151194/report.pdf 到 /my/downloads 目录

使用环境变量配置默认下载目录:

export JIRA_DOWNLOAD_PATH="/Users/username/Downloads"

下载超时

下载操作的超时时间为 5 分钟（300 秒），适合大文件下载。

错误处理

URL 格式无效: 会提示 URL 格式错误
附件不存在或无权限: 会返回相应的错误信息
目录不可写: 会提示目录不可写并建议检查权限或使用 outputPath 参数

示例输出：

📥 附件下载成功

文件: screenshot.png
大小: 150.50 KB
保存到: /tmp/151194-screenshot.png

兼容性

Node.js 版本: 18 或更高版本
Jira 版本: 7.0.9+ (使用 REST API v2)

许可证

MIT License

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Jira MCP Server

架构

功能

环境变量配置

认证方式说明

认证方式选择逻辑

获取 Jira API Token

日志配置（可选）

日志级别

输出目标

配置示例

日志格式

日志文件轮转

自定义字段配置（可选）

配置步骤

字段映射规则

安装

通过 npm 全局安装

使用 npx 运行（无需安装）

使用方法

设置环境变量

使用 API Token 认证（推荐）

使用密码认证

显式指定认证方式

Claude Desktop 配置

macOS

Windows

配置内容

使用 API Token 认证（推荐）

使用密码认证

Claude CLI 配置

基于项目添加

全局添加

使用示例

基本功能

字段发现

JQL 搜索

附件上传

支持的输入方式

附件大小限制

使用示例

错误处理

附件下载

下载方式

保存路径优先级

文件命名规则

使用示例

下载超时

错误处理

兼容性

许可证