Name: JIRA MCP服务器
Author: rrasouli

使用说明

JIRA MCP服务器

一个生产就绪的模型上下文协议服务器，为AI助手提供全面的JIRA操作。

概述

JIRA MCP服务器是 通用，生产就绪 该工具通过模型上下文协议将JIRA的全部功能带给AI助手。它支持与JIRA实例的自然语言交互，同时维护安全性、可审计性和组织标准。

兼容：

克劳德桌面版 -用于AI辅助的GUI应用程序
克劳德代码 -用于开发工作流的CLI工具
任何其他MCP兼容客户端

为什么这很重要

之前： 团队每周花费数小时完成重复的JIRA任务

反复制造类似问题
搜索相关门票
需要手动UI点击的批量操作
代码和JIRA之间的上下文切换

之后： 人工智能通过自然语言辅助JIRA操作

“使用标准标签为要素X创建故事”
“将所有QE跟踪器票证作为重复项关闭”
“查找分配给我的团队的所有未解决的bug”
与开发工作流程无缝集成

结果： JIRA管理开销减少80-90%

什么是MCP？

模型上下文协议（MCP）是一个开放标准，使人工智能助手能够安全地连接到外部工具和数据源。将其视为一个通用适配器，让Claude与您的企业系统进行交互。

运作原理

+-----------------+          +------------------+         +-------------+ 
|     Claude      |          |                  |         |             | 
|  Desktop/Code   |   MCP    |  MCP Server      |  REST   |  Jira API   |
|                 |<-------> | (This Project)   |<------->|             |
|                 | Protocol |                  |   API   |             |
+-----------------+          +------------------+         +-------------+
         ↑                           ↑  
         |                           |
         |                           | 
         ↓                           ↓
+-----------------+         +------------------+
|  Natural        |         | Uses jira CLI    |
|  Language:      |<------->| for auth & API   |
|                 |         |                  |
| "Create a story |         +------------------+
|  in PROJECT-X   |                  
|  called 'Add    |                  
|  Feature Y'"    |
+-----------------+

主要优势

标准化：适用于任何兼容MCP的客户端
安全：使用您现有的JIRA凭据
可审计的：JIRA中记录的所有操作
可扩展：易于为您的组织添加自定义工具

特性

核心业务

问题管理
创建问题（故事、任务、Bug、史诗、子任务）
编辑问题字段
添加标签和元数据
查看详细问题信息
搜索与发现
JQL（JIRA查询语言）搜索
按项目、状态、受让人、标签筛选
结构化结果格式
问题关系
链接问题（阻止、关联、重复、依赖）
创建问题层次结构
保持可追溯性
工作流操作
工作流程中的过渡问题
解决问题
在转换过程中添加评论
批量操作
同时解决多个问题
批量标签更新
大规模转型

技术特性

通用设计：适用于任何JIRA实例
项目不可知：支持所有项目类型
错误处理：全面的重试逻辑和错误报告
超时管理：可配置的操作超时
JSON响应：结构化、可解析的输出
CLI集成：利用久经考验的jira cli工具

建筑

系统设计

+-----------------------------------------------------------------+
|                         User Layer                              |
|                                                                 |
|  +--------------+     +--------------+     +--------------+     |
|  |   Claude     |     |   Other MCP  |     |   Future     |     |
|  | Desktop/code |     |   Clients    |     |   Clients    |     |
|  +------+-------+     +------+-------+     +------+-------+     |
|         |                    |                    |             |
+---------+--------------------+--------------------+-------------+
          |                    |                    |
          +--------------------+--------------------+
                               |
                   Model Context Protocol
                               |
+------------------------------+----------------------------------+
|                   MCP Server Layer                              |
|                              |                                  |
|  +---------------------------v----------------------------+     |
|  |             FastMCP Server (server.py)                  |    |
|  |                                                         |    |
|  |  +-------------+  +-------------+  +-------------+      |    |
|  |  |create_issue()|  |search_issues|  |link_issues()|     |    |
|  |  +-------------+  +-------------+  +-------------+      |    |
|  |                                                         |    |
|  |  +-------------+  +-------------+  +-------------+      |    |
|  |  |transition() |  |add_labels() |  |batch_close()|      |    |
|  |  +-------------+  +-------------+  +-------------+      |    |
|  |                                                         |    |
|  |  +-------------+                                        |    |
|  |  |view_issue() |         7 Tools Total                  |    |
|  |  +-------------+                                        |    |
|  +--------------------------+------------------------------+    |
|                             |                                   |
|                    run_jira_command()                           |
|                             |                                   |
+-----------------------------+-----------------------------------+
                              |
+-----------------------------v------------------------------------+
|                    Integration Layer                             |
|                                                                  |
|  +----------------------------------------------------------+    |
|  |         jira-cli (ankitpokhrel/jira-cli)                 |    |
|  |                                                          |    |
|  |  - Authentication management                             |    |
|  |  - Secure credential storage                             |    |
|  |  - REST API abstraction                                  |    |
|  +---------------------------+------------------------------+    |
|                              |                                   |
+------------------------------+-----------------------------------+
                               |
                          HTTPS/TLS
                               |
+------------------------------v-----------------------------------+
|                      JIRA Instance                               |
|                                                                  |
|  +-----------------------------------------------------------+   |
|  |                    JIRA REST API                          |   |
|  |                                                           |   |
|  |  - Issue operations     - Search (JQL)                    |   |
|  |  - Workflow transitions - Link management                 |   |
|  |  - Field updates        - Audit logging                   |   |
|  +-----------------------------------------------------------+   |
|                                                                  |
+------------------------------------------------------------------+

数据流

用户请求：对Claude Desktop的自然语言查询
工具选择：Claude确定要使用的适当MCP工具
MCP协议：工具调用通过stdio发送到MCP服务器
命令执行：服务器转换为jira-cli命令
API调用：jira-cli对jira进行经过身份验证的REST API调用
响应处理：分析并构造JIRA API响应
结果返回：通过MCP协议返回JSON格式的结果
用户演示文稿：Claude以自然语言为用户格式化结果

安全模型

+-------------------------------------------------------------+
|                    Security Boundaries                      |
|                                                             |
|  User Credentials  --->  jira-cli Storage  --->  JIRA API   |
|  (Initial Setup)         (Encrypted)            (TLS 1.2+)  |
|                                                             |
|  +------------------------------------------------------+   |
|  |  Permissions Model                                   |   |
|  |                                                      |   |
|  |  - Server runs with user's JIRA permissions          |   |
|  |  - No privilege escalation                           |   |
|  |  - All operations audited in JIRA                    |   |
|  |  - No credential storage in MCP server               |   |
|  +------------------------------------------------------+   |
+-------------------------------------------------------------+

先决条件

必需

Python 3.10或更高版本
```
python3 --version  # Should be 3.10+
```

吉拉CLI (ankitpokhrel/jira cli)

# macOS
brew install ankitpokhrel/jira-cli/jira-cli

# Linux
curl -L https://github.com/ankitpokhrel/jira-cli/releases/download/v1.4.0/jira_1.4.0_linux_x86_64.tar.gz | tar xz
sudo mv bin/jira /usr/local/bin/

# Windows
scoop install jira-cli

JIRA访问
- 有效的JIRA帐户
- API令牌或凭据
- 适当的项目权限

可选的

克劳德桌面版 -用于人工智能辅助的JIRA操作
虚拟环境 -建议用于Python隔离

快速开始

在5分钟内起床跑步。

适用于：

克劳德桌面版 （GUI应用程序）
克劳德代码 （CLI工具）

使用Makefile（推荐）

# 1. Clone the repository
git clone https://github.com/rrasouli/jira-mcp-server.git ~/Documents/GitHub/jira-mcp-server
cd ~/Documents/GitHub/jira-mcp-server

# 2. Install everything (jira-cli + Python dependencies)
make install

# 3. Configure jira CLI
jira init

# 4. Run interactive setup
make setup

# 5. Restart Claude Desktop

# 6. Test it out
# Ask Claude: "Create a test story in PROJECT-X called 'MCP Integration Test'"

使用安装脚本

cd ~/Documents/GitHub/jira-mcp-server
./setup.sh

安装程序将：

检查先决条件
创建Python虚拟环境
安装依赖项
配置JIRA CLI
更新Claude桌面配置
验证安装

Makefile命令

该项目包括一个全面的Makefile，便于设置和开发：

make help              # Show all available commands
make status            # Show installation status
make install           # Full installation (jira-cli + Python deps)
make install-jira-cli  # Install jira CLI only
make setup             # Run interactive setup
make run               # Start the MCP server
make test              # Run tests
make lint              # Check code style
make format            # Format code with black
make clean             # Clean build artifacts

常见工作流：

# First-time setup
make install
make setup

# Development
make dev-setup         # Install development dependencies
make test              # Run tests
make lint              # Check code style
make format            # Format code

# Check what's installed
make status

安装

选项1：使用Makefile（推荐）

cd ~/Documents/GitHub/jira-mcp-server
make install    # Installs jira-cli and Python dependencies
make setup      # Interactive configuration

Makefile会自动检测您的操作系统（macOS/Linux）并相应地安装先决条件。

选项2：使用安装脚本

cd ~/Documents/GitHub/jira-mcp-server
./setup.sh

按照交互式提示配置JIRA实例和默认项目。

选项3：手动安装

# 1. Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 2. Install dependencies
pip install --upgrade pip
pip install mcp

# 3. Configure JIRA CLI
jira init
# Provide:
# - JIRA server URL (e.g., https://jira.company.com)
# - Authentication method (Personal Access Token recommended)
# - Your credentials

# 4. Make server executable
chmod +x server.py

# 5. Test the server
python server.py
# Server starts and waits for MCP protocol messages

选项4：软件包安装

cd ~/jira-mcp-server
pip install -e .

这将服务器安装为Python包，使其在系统范围内可用。

配置

此JIRA MCP服务器与 克劳德桌面（GUI）和克劳德代码（CLI）.

快速参考：克劳德桌面vs克劳德代码

特性	克劳德桌面	克劳德代码
配置文件	`~/Library/Application Support/Claude/claude_desktop_config.json`	`~/.claude.json`
配置范围	全局（所有对话）	每个项目（每个目录）
MCP位置	`mcpServers` 根级	`projects.<path>.mcpServers`
服务器名称	通常 `jira`	可以是 `jira` 或 `jira-prod`
需要重新启动	是（重新启动应用程序）	是（在目录中退出/重新启动）

主要区别： 克劳德桌面有全球 MCP配置，而Claude Code 每个项目 配置。这意味着您必须为Claude Code中的每个工作目录分别配置jira prod。

配置优先

设置按以下顺序加载：

环境变量 （最高优先级）
持久配置文件 ~/.jira-mcp-config.json
默认值 （最低优先级）

快速入门：交互式配置

运行配置向导以持久保存您的设置：

python server.py --configure

这创造了 ~/.jira-mcp-config.json 安全权限（0600）包含：

JIRA_URL：您的JIRA实例URL（必填）
JIRA_API_TOKEN公司：您的API令牌（必需）
JIRA_anable_WRITE：启用写入操作-true/false（可选，默认值：false）
JIRA.EMAIL：仅适用于传统的basic_auth（可选，现代JIRA不需要）

优点：

设置在会话之间保持不变
无需每次都设置环境变量
安全文件权限（仅限所有者读/写）
查看当前配置： python server.py --show-config
重置配置： python config.py reset

环境变量

您可以使用环境变量覆盖持久配置：

# Required
export JIRA_URL="https://jira.your-company.com"
export JIRA_API_TOKEN="your-api-token-here"

# Optional
export JIRA_ENABLE_WRITE="true"  # Enable write operations (default: false)

# Legacy only (not needed for modern JIRA)
export JIRA_EMAIL="your.email@company.com"  # Only for old basic_auth

选项1:克劳德桌面配置（GUI）

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jira": {
      "command": "python",
      "args": ["/absolute/path/to/jira-mcp-server/server.py"],
      "env": {
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_DEFAULT_PROJECT": "YOUR_PROJECT"
      }
    }
  }
}

重要提示：

使用绝对路径（不 ~ 或 $HOME)
用实际值替换占位符
配置更改后重新启动Claude Desktop

配置文件位置：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json

选项2:Claude代码配置（CLI）

重要： 克劳德代码使用 每个项目MCP配置，不是全局配置。

理解Claude Code的配置模型

与Claude Desktop不同，Claude Code 不支持全局MCP服务器配置。MCP服务器在中按项目配置 ~/.claude.json 在每个项目的目录路径下。

主要区别：

克劳德桌面版：用途 ~/Library/Application Support/Claude/claude_desktop_config.json （全球）
克劳德代码：用途 ~/.claude.json 每个项目 mcpServers 部分（无全局选项）

这意味着：

MCP服务器必须为每个工作目录单独配置
不同目录中的会话不会共享MCP服务器配置
您需要在希望可用的项目之间复制MCP服务器配置

按项目配置 `~/.claude.json`

Claude Code将特定于项目的设置存储在 ~/.claude.json。每个项目目录都有自己的 mcpServers 章节：

{
  "projects": {
    "/Users/YOUR_USERNAME/Documents": {
      "mcpServers": {
        "jira-prod": {
          "type": "stdio",
          "command": "/Users/YOUR_USERNAME/Documents/GitHub/jira-mcp-server/venv/bin/python",
          "args": [
            "/Users/YOUR_USERNAME/Documents/GitHub/jira-mcp-server/server.py"
          ],
          "env": {}
        }
      }
    },
    "/Users/YOUR_USERNAME/Documents/GitHub/my-project": {
      "mcpServers": {
        "jira-prod": {
          "type": "stdio",
          "command": "/Users/YOUR_USERNAME/Documents/GitHub/jira-mcp-server/venv/bin/python",
          "args": [
            "/Users/YOUR_USERNAME/Documents/GitHub/jira-mcp-server/server.py"
          ],
          "env": {}
        }
      }
    }
  }
}

要将jira prod添加到项目中，请执行以下操作：

在中查找项目的部分 ~/.claude.json
找到 mcpServers 对象（将为空 {} 如果未配置）
添加jira prod配置：

"mcpServers": {
  "jira-prod": {
    "type": "stdio",
    "command": "/Users/YOUR_USERNAME/Documents/GitHub/jira-mcp-server/venv/bin/python",
    "args": [
      "/Users/YOUR_USERNAME/Documents/GitHub/jira-mcp-server/server.py"
    ],
    "env": {}
  }
}

退出并重新启动该目录中的Claude Code

要将jira prod添加到多个项目中，请执行以下操作：

你需要复制 jira-prod 每个项目的配置 mcpServers 部分。例如：

{
  "projects": {
    "/Users/YOUR_USERNAME/Documents": {
      "mcpServers": {
        "jira-prod": { ... }
      }
    },
    "/Users/YOUR_USERNAME/Documents/GitHub/project-a": {
      "mcpServers": {
        "jira-prod": { ... }
      }
    },
    "/Users/YOUR_USERNAME/Documents/GitHub/project-b": {
      "mcpServers": {
        "jira-prod": { ... }
      }
    }
  }
}

为什么是按项目配置？

不同的项目可能需要不同的MCP服务器
按工作目录隔离工具可用性
防止MCP服务器在无关的上下文中加载

验证MCP服务器是否已加载：

# When you start Claude Code in a configured directory, you should see:
# "MCP server jira-prod initialized"

# In an unconfigured directory, jira-prod won't be available

配置后：

如果正在运行，则退出Claude代码
在配置的目录中重新启动Claude Code
问Claude：“在YOUR_PROJECT中创建一个名为‘MCP集成测试’的测试故事”

选项3：光标配置

Cursor是一个流行的AI驱动的代码编辑器，支持MCP服务器。本节提供完整的设置说明。

Cursor的先决条件

获取Jira API代币：
- 访问https://id.atlassian.com/manage-profile/security/api-tokens
- 点击“创建API令牌”
- 给它一个描述性的名称（例如，“光标MCP服务器”）
- 复制并安全保存令牌

了解你的道路：

# Find absolute path to jira-mcp-server
cd ~/Documents/GitHub/jira-mcp-server
pwd
# Copy this path - you'll need it for configuration

配置步骤

创建或编辑 ~/.cursor/mcp.json （全局配置）：

{
  "mcpServers": {
    "jira-prod": {
      "command": "/absolute/path/to/jira-mcp-server/venv/bin/python",
      "args": ["/absolute/path/to/jira-mcp-server/server.py"],
      "env": {
        "JIRA_URL": "https://your-instance.atlassian.net",
        "JIRA_DEFAULT_PROJECT": "MYPROJECT",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

特定路径示例：

{
  "mcpServers": {
    "jira-prod": {
      "command": "/Users/YOUR_USERNAME/Documents/GitHub/jira-mcp-server/venv/bin/python",
      "args": ["/Users/YOUR_USERNAME/Documents/GitHub/jira-mcp-server/server.py"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_DEFAULT_PROJECT": "MYPROJECT",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

重要配置说明：

使用 绝对路径 （例如。， /Users/username/... 不 ~/...)
替换 YOUR_USERNAME 使用您的实际用户名
替换 YOUR-PROJECT-KEY 使用默认的Jira项目
替换 your-email@company.com 使用您的Jira帐户电子邮件
替换 your-api-token-here 使用步骤1中的API令牌
这 JIRA_EMAIL 和 JIRA_API_TOKEN 字段为 必需的 对于光标

备选方案：特定于工作区的配置

创建 .cursor/mcp.json 在项目目录中查看项目特定设置：

{
  "mcpServers": {
    "jira-prod": {
      "command": "/absolute/path/to/jira-mcp-server/venv/bin/python",
      "args": ["/absolute/path/to/jira-mcp-server/server.py"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_DEFAULT_PROJECT": "MYPROJECT",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-token"
      }
    }
  }
}

配置后

完全重新启动游标 （不仅仅是重新加载窗口）
验证MCP服务器是否已连接：
- 在光标中查找绿色指示灯或“MCP”状态
- 服务器应显示为“jira prod”（已连接）
测试集成：
- 询问Cursor：“显示[YOUR-PROJECT]中的所有未解决问题”
- 询问Cursor：“在[YOUR-PROJECT]中创建一个名为‘MCP集成测试’的测试任务”

光标设置故障排除

问题：MCP服务器显示为红色/已断开连接

症状：

光标中“jira prod”旁边的红色圆圈
错误： 401 Unauthorized 或身份验证失败
服务器显示为已断开连接

解决：

验证凭据是否已在中设置 env 章节：

"env": {
  "JIRA_URL": "https://your-instance.atlassian.net",
  "JIRA_DEFAULT_PROJECT": "PROJECT",
  "JIRA_EMAIL": "your-email@company.com",      // Required!
  "JIRA_API_TOKEN": "your-token-here"          // Required!
}

手动测试凭据：

curl -u "your-email@company.com:your-api-token" \
  "https://your-instance.atlassian.net/rest/api/3/myself"

应该返回您的用户信息，而不是401错误。

验证绝对路径：

// CORRECT
"command": "/Users/username/Documents/GitHub/jira-mcp-server/venv/bin/python"

// WRONG - do not use these
"command": "~/Documents/GitHub/jira-mcp-server/venv/bin/python"
"command": "./venv/bin/python"
"command": "python"

检查虚拟环境是否存在：

ls -la /Users/YOUR_USERNAME/Documents/GitHub/jira-mcp-server/venv/bin/python
# Should show the Python interpreter, not "No such file"

如果已过期，则重新生成API令牌：
- 访问https://id.atlassian.com/manage-profile/security/api-tokens
- 删除旧令牌
- 创建新令牌
- 更新 ~/.cursor/mcp.json 使用新令牌
- 重新启动游标

问题：“Python jira库basic_auth模式失败，401”

这是Python的一个已知问题 jira 库对重定向的处理。库可能会在重定向时删除身份验证标头，而curl会保留它们。

解决方案： 确保两者 JIRA_EMAIL 和 JIRA_API_TOKEN 设置在 env 部分。这允许服务器使用正确的身份验证标头。

问题：找不到配置文件

如果光标找不到 ~/.cursor/mcp.json:

# Create the directory if it doesn't exist
mkdir -p ~/.cursor

# Create the configuration file
cat > ~/.cursor/mcp.json << 'EOF'
{
  "mcpServers": {
    "jira-prod": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "JIRA_URL": "https://your-instance.atlassian.net",
        "JIRA_DEFAULT_PROJECT": "PROJECT",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-token"
      }
    }
  }
}
EOF

问题：更改未生效

确保您已保存 ~/.cursor/mcp.json
完全退出并重新启动Cursor（而不仅仅是重新加载）
检查Cursor的日志，查看MCP服务器初始化错误

游标安全注意事项

~/.cursor/mcp.json 包含敏感凭据
不要将此文件提交到版本控制
添加 .gitignore 如果使用特定于工作区的 .cursor/mcp.json
文件权限应仅限用户（600）：
```
chmod 600 ~/.cursor/mcp.json
```

光标使用示例

配置后，您可以在Cursor中使用自然语言：

You: "Show me all open bugs in PROJECT assigned to me"

Cursor: [Uses jira-prod MCP server]
Found 3 open bugs:
- PROJECT-101: Bug description here
- PROJECT-102: Another bug description
- PROJECT-103: Yet another bug

You: "Create a story in PROJECT called 'Add new feature X'"

Cursor: [Uses jira-prod MCP server]
Created story PROJECT-150: Add new feature X
URL: https://your-instance.atlassian.net/browse/PROJECT-150

可用工具

1.创建_发行

使用全面的元数据创建新的JIRA问题。

参数：

summary （必填）：发行标题
issue_type （必填）：故事、任务、Bug、史诗、子任务
project （可选）：项目密钥，用途 JIRA_DEFAULT_PROJECT 如果未指定
description （可选）：详细的问题描述
labels （可选）：逗号分隔的标签

退货：

{
  "issue_key": "PROJECT-1234",
  "url": "https://jira.company.com/browse/PROJECT-1234",
  "success": true
}

示例用法：

"Create a story in PLATFORM called 'Add OAuth2 authentication support'
with description 'Implement OAuth2 flow for third-party integrations'
and labels security,authentication,oauth"

2.搜索问题

使用JIRA查询语言（JQL）搜索问题。

参数：

jql （必填）：JQL查询字符串
max_results （可选）：返回的最大结果数（默认值：50）

退货：

{
  "jql": "project = PLATFORM AND status = Open",
  "count": 12,
  "issues": [
    {
      "key": "PLATFORM-1234",
      "summary": "Add OAuth2 support",
      "status": "Open",
      "assignee": "john.doe",
      "url": "https://jira.company.com/browse/PLATFORM-1234"
    }
  ]
}

查询示例：

"Search for all critical bugs assigned to me"
→ JQL: assignee = currentUser() AND priority = Critical AND type = Bug

"Find open issues in PLATFORM project with label 'security'"
→ JQL: project = PLATFORM AND status = Open AND labels = security

"Show all stories created this week"
→ JQL: type = Story AND created >= startOfWeek()

3.链接问题

在问题之间建立关系。

参数：

inward_issue （必填）：第一个问题密钥
outward_issue （必填）：第二个问题密钥
link_type （必填）：块、相关、重复、依赖

链接类型：

blocks：外部_发行块内部_发行
Related：问题相关
Duplicate：外发_内发_副本
Depend：内向问题取决于外向问题

例子：

"Link PLATFORM-1234 and PLATFORM-1235 where 1235 blocks 1234"

4.过渡问题

在工作流程中移动问题。

参数：

issue_key （必填）：问题到过渡
state （必填）：目标状态（进行中、完成、关闭等）
resolution （可选）：分辨率类型（完成、不修复、复制等）
comment （可选）：过渡期间要添加的注释

例子：

"Close PLATFORM-1234 as Duplicate with comment 'Duplicate of PLATFORM-999'"

5.附加标签

为现有问题添加标签。

参数：

issue_key （必填）：待更新的问题
labels （必填）：逗号分隔的标签

例子：

"Add labels urgent,customer-facing,security to PLATFORM-1234"

6.view_issue

获取有关问题的详细信息。

参数：

issue_key （必填）：待查看问题

退货： 完整的问题详细信息，包括描述、评论、附件和元数据。

例子：

"Show me details of PLATFORM-1234"

7.批次_类别_问题

以相同的解决方案同时解决多个问题。

参数：

issue_keys （必填）：逗号分隔的问题密钥
resolution （可选）：分辨率类型（默认值：“复制”）
comment （可选）：对所有问题添加评论

退货：

{
  "total": 3,
  "results": [
    {
      "issue_key": "QE-100",
      "state": "Closed",
      "resolution": "Duplicate",
      "success": true
    }
  ]
}

例子：

"Close QE-100, QE-101, QE-102 as duplicates with comment 'Consolidated into QE-99'"

使用示例

使用克劳德桌面与克劳德代码

同一个MCP服务器可与两个客户端一起使用，但用户体验不同：

Claude桌面（GUI）示例

打开克劳德桌面应用程序
开始对话
用自然语言提问：

You: "Create a story in MYTEAM project called 'Add RuntimeClass support for Windows workloads'
with labels windows,winc,runtimeclass"

Claude: I'll create that story for you using the JIRA MCP server.
[Uses create_issue() tool]

Created story MYTEAM-1234: Add RuntimeClass support for Windows workloads
View at: https://issues.myorg.com/browse/MYTEAM-1234
Labels: windows, winc, runtimeclass

Claude代码（CLI）示例

$ claude

You: Create a story in MYTEAM project called 'Add RuntimeClass support'

Claude: I'll create that JIRA story for you.
[MCP server jira initialized]
[Uses jira.create_issue tool]

Created story MYTEAM-1234: Add RuntimeClass support
URL: https://issues.myorg.com/browse/MYTEAM-1234

You: Now search for all open issues in MYTEAM with label 'windows'

Claude: Searching JIRA...
[Uses jira.search_issues tool]

Found 12 open issues:
- MYTEAM-1234: Add RuntimeClass support
- MYTEAM-1230: Fix container isolation
- MYTEAM-1225: Update Windows node configuration
...

主要区别：

克劳德桌面版：图形界面、更丰富的格式、持久的对话
克劳德代码：基于终端，开发人员更快，与shell工作流集成

两者都支持相同的MCP工具和功能！

示例1：使用子任务创建功能史诗

用户： “为PLATFORM项目中的第二季度身份验证改进创造史诗”

克劳德使用： create_issue()

{
  "summary": "Q2 Authentication Improvements",
  "issue_type": "Epic",
  "project": "PLATFORM",
  "description": "Enhance authentication system with OAuth2, 2FA, and session management",
  "labels": "q2-2024,security,authentication"
}

跟进： 创建三个子任务：OAuth2实现、2FA设置和会话超时

Claude会自动创建三个链接的子任务。

示例2：关闭重复的QE跟踪器

用户： “查找所有打开的QE跟踪器票证，并将其作为副本关闭”

克劳德工作流程：

用途 search_issues() 使用JQL： type = "QE Tracker" AND status = Open
从结果中提取问题密钥
用途 batch_close_issues() 一次性全部关闭

结果： 15张票在几秒钟内关闭，而不是手动点击UI。

示例3：Sprint计划自动化

用户： “查找平台项目中的所有高优先级错误，并将其移动到进行中”

克劳德工作流程：

搜索： project = PLATFORM AND priority = High AND type = Bug
对于每个问题： transition_issue(key, "In Progress")
添加标签： add_labels(key, "sprint-12")

示例4：发布跟踪

用户： “使用标准发布任务为v2.5.0创建发布跟踪器”

定制工具 （您可以添加此项）：

@mcp.tool()
def create_release_tracker(version: str, target_date: str) -> str:
    """Create standardized release tracker with subtasks"""
    # Create epic
    epic = create_issue(f"Release {version}", "Epic", description=f"Release {version} - Target: {target_date}")

    # Create standard subtasks
    tasks = [
        "Code freeze",
        "QE testing complete",
        "Documentation review",
        "Release notes published",
        "Production deployment"
    ]

    for task in tasks:
        subtask = create_issue(task, "Sub-task", ...)
        link_issues(epic["issue_key"], subtask["issue_key"], "Related")

部署

看部署_ GIDE.md 以制定全面的部署战略。

快速部署选项

选项1：内部Git仓库 （推荐）

git remote add origin https://github.com/your-org/jira-mcp-server.git
git push -u origin main

选项2：内部PyPI

python -m build
twine upload --repository-url https://pypi.your-org.com dist/*

选项3：共享网络驱动器

cp -r ~/jira-mcp-server /shared/network/tools/

选项4：容器注册表

docker build -t your-registry.com/jira-mcp-server:1.0.0 .
docker push your-registry.com/jira-mcp-server:1.0.0

安全

凭据管理

**推荐：jira-cli凭据存储**

jira-cli安全存储的凭据
系统密钥链集成（macOS密钥链、Windows凭据管理器、Linux密钥服务）
MCP服务器代码或配置中没有凭据

**不推荐：环境变量**

进程列表中可见的凭据
意外提交版本控制的风险
不如钥匙链存储安全

权限模型

MCP服务器通过以下方式运行 您的JIRA权限:

无法升级权限
尊重项目级权限
根据JIRA的安全政策
JIRA审核的所有操作

API代币最佳实践

定期旋转：每90天更改一次API令牌
最小权限：授予所需的最低权限
从不承诺：将令牌添加到 .gitignore
审核访问权限：每月审查JIRA审计日志
撤销未使用：不再需要时删除令牌

网络安全

通过HTTPS/TLS 1.2进行的所有JIRA API调用+
已强制执行证书验证
无代理凭据存储
尊重公司网络政策

故障排除

常见问题

“未找到jira CLI”

问题： jira-cli未安装或未在PATH中

解决方案：

# macOS
brew install ankitpokhrel/jira-cli/jira-cli

# Linux
curl -L https://github.com/ankitpokhrel/jira-cli/releases/latest/download/jira_linux_x86_64.tar.gz | tar xz
sudo mv bin/jira /usr/local/bin/

# Verify installation
jira version

“命令超时”

问题： JIRA API调用耗时超过30秒

解决方案： 增加超时时间 server.py:

# Line 48
timeout=60  # Increase from 30 to 60 seconds

对于慢速JIRA实例，考虑90-120秒超时。

“需要项目”

问题： 未配置默认项目

解决方案：

# Set in Claude Desktop config
export JIRA_DEFAULT_PROJECT="YOUR_PROJECT"

# Or always specify project in requests
"Create a story in PLATFORM called ..."

“身份验证失败”

问题： JIRA凭据无效或已过期

解决方案：

# Reconfigure jira-cli
jira init

# Test authentication
jira issue list --jql "assignee = currentUser()"

# Regenerate API token if using PAT
# Visit: https://your-jira.com/secure/ViewProfile.jspa?selectedTab=com.atlassian.pats.pats-plugin:jira-user-personal-access-tokens

“MCP服务器没有响应”

问题： 服务器进程未启动或崩溃

解决方案：

# Test server directly
cd ~/jira-mcp-server
source venv/bin/activate
python server.py

# Check for errors in output
# Verify Python version
python --version  # Must be 3.10+

# Reinstall dependencies
pip install --upgrade mcp

“Claude Desktop看不到服务器”

问题： 配置加载不正确

解决方案：

验证配置文件位置（请参阅配置部分）
检查JSON语法（使用 Jsonlin.com)
确保绝对路径（不是 ~ 或 $HOME)
完全重新启动克劳德桌面
检查克劳德桌面日志：
- macOS： ~/Library/Logs/Claude/
- Linux： ~/.config/Claude/logs/

“jira prod在某些Claude Code会话中不可用”

问题： MCP服务器在一个目录中工作，但在其他目录中不工作

原因： 克劳德代码使用 每个项目MCP配置，不是全局配置。服务器仅在您配置它的目录中可用。

解决方案：

检查您所在的目录：

pwd
# Example: /Users/yourname/Documents/GitHub/release

编辑 ~/.claude.json 并找到您项目的部分：

# Open the config file
code ~/.claude.json  # or your editor of choice

# Find the section for your current directory
# Look for: "/Users/yourname/Documents/GitHub/release": {

将jira prod添加到该项目中 mcpServers:

"/Users/yourname/Documents/GitHub/release": {
  "mcpServers": {
    "jira-prod": {
      "type": "stdio",
      "command": "/Users/yourname/Documents/GitHub/jira-mcp-server/venv/bin/python",
      "args": [
        "/Users/yourname/Documents/GitHub/jira-mcp-server/server.py"
      ],
      "env": {}
    }
  }
}

退出并重新启动该目录中的Claude Code

要使jira prod在任何地方都可用：

不幸的是，Claude Code没有全局MCP配置。您必须添加 jira-prod 每个项目的配置 mcpServers 部分在 ~/.claude.json.

要配置的常用目录：

您的主目录： /Users/yourname/Documents
您使用的每个Git存储库
任何工作树目录

多项目配置示例：

{
  "projects": {
    "/Users/yourname/Documents": {
      "mcpServers": {
        "jira-prod": { ... }
      }
    },
    "/Users/yourname/Documents/GitHub/repo-a": {
      "mcpServers": {
        "jira-prod": { ... }
      }
    },
    "/Users/yourname/Documents/GitHub/repo-b": {
      "mcpServers": {
        "jira-prod": { ... }
      }
    }
  }
}

贡献

看贡献.md 发展指南。

快速贡献指南

分叉存储库
创建要素分支： git checkout -b feature/amazing-feature
进行更改并彻底测试
承诺： git commit -m "Add amazing feature"
推： git push origin feature/amazing-feature
打开拉取请求

添加自定义工具

@mcp.tool()
def your_custom_tool(param1: str, param2: int) -> str:
    """
    Description of your custom tool.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        JSON string with structured result
    """
    # Your implementation
    result = run_jira_command(["your", "command", "here"])

    return json.dumps({
        "success": result["success"],
        "data": result["output"]
    })

支持

资源

JIRA CLI文档: https://github.com/ankitpokhrel/jira-cli
MCP协议规范: https://modelcontextprotocol.io
JIRA REST API参考: https://developer.atlassian.com/cloud/jira/platform/rest/v3/

报告问题

报告错误或请求功能：https://github.com/rrasouli/jira-mcp-server/issues

许可证

此项目根据GNU通用公共许可证v2.0获得许可-请参阅许可证文件以获取详细信息。

更新日志

版本1.0.0（2024-01-15）

初始版本
7个核心JIRA工具
通用JIRA实例支持
FastMCP集成
自动设置脚本
全面的文件

致谢

建于 FastMCP
用途吉拉cli 用于JIRA集成
实现模型上下文协议

问题？ 联系MCP团队mcp-support@your-company.com

使用说明

JIRA MCP服务器

目录

概述

为什么这很重要

什么是MCP？

运作原理

主要优势

特性

核心业务

技术特性

建筑

系统设计

数据流

安全模型

先决条件

必需

可选的

快速开始

使用Makefile（推荐）

使用安装脚本

Makefile命令

安装

选项1：使用Makefile（推荐）

选项2：使用安装脚本

选项3：手动安装

选项4：软件包安装

配置

快速参考：克劳德桌面vs克劳德代码

配置优先

快速入门：交互式配置

环境变量

选项1:克劳德桌面配置（GUI）

选项2:Claude代码配置（CLI）

理解Claude Code的配置模型

按项目配置 ~/.claude.json

选项3：光标配置

Cursor的先决条件

配置步骤

配置后

光标设置故障排除

游标安全注意事项

光标使用示例

可用工具

1.创建_发行

2.搜索问题

3.链接问题

4.过渡问题

5.附加标签

6.view_issue

7.批次_类别_问题

使用示例

使用克劳德桌面与克劳德代码

Claude桌面（GUI）示例

Claude代码（CLI）示例

示例1：使用子任务创建功能史诗

示例2：关闭重复的QE跟踪器

示例3：Sprint计划自动化

示例4：发布跟踪

部署

快速部署选项

安全

凭据管理

权限模型

API代币最佳实践

网络安全

故障排除

常见问题

“未找到jira CLI”

“命令超时”

“需要项目”

“身份验证失败”

“MCP服务器没有响应”

“Claude Desktop看不到服务器”

“jira prod在某些Claude Code会话中不可用”

贡献

快速贡献指南

添加自定义工具

支持

资源

按项目配置 `~/.claude.json`