JIRA MCP服务器
一种模型上下文协议（MCP）服务器实现，提供对JIRA数据的访问，包括关系跟踪、优化的数据有效载荷和AI上下文窗口的数据清理。
ℹ️ 有一个单独的MCP服务器 对于汇流
______________________________________________________________________
Jira云和Jira服务器（数据中心）支持
此MCP服务器同时支持 吉拉云 和 Jira服务器（数据中心） 实例。您可以通过设置来选择要使用的类型 JIRA_TYPE 环境变量：
cloud（默认）：适用于Jira Cloud（Atlassian托管）server：适用于Jira服务器/数据中心（自托管）
服务器将自动为所选类型使用正确的API版本和身份验证方法。
______________________________________________________________________
特性
- 使用JQL搜索JIRA问题（每个请求最多50个结果）
- 使用评论历史记录和优化的有效载荷检索史诗级儿童（每个请求最多100个问题）
- 获取详细的问题信息，包括评论和相关问题
- 创建、更新和管理JIRA问题
- 为问题添加评论
- 从Atlassian文档格式中提取问题提及
- 跟踪问题关系（提及、链接、父母/孩子、史诗）
- 清理和转换丰富的JIRA内容，以提高AI上下文效率
- 支持具有安全多部分上传处理的文件附件
- 支持Jira Cloud和Jira Server（数据中心）API
- 双传输模式：STDIO（默认）和流式HTTP（MCP 2025-03-26），适用于Postman和MCP Inspector等工具
先决条件
- 包子 （v1.0.0或更高版本）
- 具有API访问权限的JIRA帐户
环境变量
JIRA_API_TOKEN=your_api_token # API token for Cloud, PAT or password for Server/DC
JIRA_BASE_URL=your_jira_instance_url # e.g., https://your-domain.atlassian.net
JIRA_USER_EMAIL=your_email # Your Jira account email
JIRA_TYPE=cloud # 'cloud' or 'server' (optional, defaults to 'cloud')
JIRA_AUTH_TYPE=basic # 'basic' or 'bearer' (optional, defaults to 'basic')
TRANSPORT_MODE=stdio # 'stdio' or 'http' (optional, defaults to 'stdio')
HTTP_PORT=3000 # Port for HTTP transport (optional, defaults to 3000)身份验证方法
- 吉拉云：使用带有基本身份验证的API令牌
- 在以下位置创建API令牌： - 集 JIRA_AUTH_TYPE=basic （默认）
- Jira服务器/数据中心:
- 基本认证：使用用户名/密码或API令牌 - 集 JIRA_AUTH_TYPE=basic （默认） - 承载者身份：使用个人访问令牌（PAT）-数据中心8.14.0中提供+ - 在配置文件设置中创建PAT - 集 JIRA_AUTH_TYPE=bearer - 使用PAT作为您的 JIRA_API_TOKEN
安装和设置
1.克隆存储库
git clone [repository-url]
cd jira-mcp2.安装依赖项并构建
bun install
bun run build3.配置MCP服务器
服务器支持两种传输模式： 工作室 （默认值，适用于Claude Desktop/Cline）和 超文本传输协议 （适用于Postman和其他基于HTTP的客户端）。
选项A:STDIO传输（默认-克劳德桌面/Cline）
编辑相应的配置文件：
macOS：
- 克莱恩：
~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json - 克劳德桌面：
~/Library/Application Support/Claude/claude_desktop_config.json
窗户：
- 克莱恩：
%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json - 克劳德桌面：
%APPDATA%\Claude Desktop\claude_desktop_config.json
Linux：
- 克莱恩：
~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json - 克劳德桌面： _遗憾的是，它还不存在_
在下面添加以下配置 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"
}
}
}
}选项B：流式HTTP传输（MCP检查器和邮递员）
- 以HTTP模式启动服务器：
# Set environment variables
export JIRA_API_TOKEN="your_api_token"
export JIRA_BASE_URL="your_jira_instance_url"
export JIRA_USER_EMAIL="your_email"
export TRANSPORT_MODE="http"
export HTTP_PORT="3000" # optional, defaults to 3000
# Run the server
bun run build/index.js或者使用 .env 文件：
# .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
TRANSPORT_MODE=http
HTTP_PORT=3000- 服务器将从Streamable HTTP端点开始：
╔════════════════════════════════════════════════════════════╗
║ 🚀 JIRA MCP Server - Streamable HTTP Transport ║
╠════════════════════════════════════════════════════════════╣
║ Protocol: MCP 2025-03-26 (Streamable HTTP) ║
║ Endpoint: http://localhost:3000/mcp ║
║ Health Check: http://localhost:3000/health ║
║ ║
║ 🔧 Supported Methods: ║
║ GET /mcp → Establish SSE connection ║
║ POST /mcp → Send JSON-RPC message ║
║ DELETE /mcp → Terminate session ║
╚════════════════════════════════════════════════════════════╝- 配置MCP检查器：
在MCP Inspector v0.15.x+中，添加一个新的服务器连接：
{
"mcpServers": {
"jira": {
"type": "sse",
"url": "http://localhost:3000/mcp"
}
}
}- 配置邮差MCP客户端：
在Postman中，添加新的MCP服务器连接：
- 统一资源定位符:
http://localhost:3000/mcp - 方法：获取
- 运输：SSE（服务器发送事件）
或导入提供的Postman收藏： tests/manual/postman_collection.json
该服务器实现了具有完整会话管理的MCP Streamable HTTP协议（2025-03-26），并与MCP Inspector v0.15.x和Postman MCP客户端兼容。
4.重新启动MCP服务器
用于STDIO模式：在Cline的MCP设置中，重新启动MCP服务器。重新启动Claude Desktop以加载新的MCP服务器。
对于HTTP模式：只需使用以下命令运行服务器 TRANSPORT_MODE=http 环境变量集。
发展
运行测试：
bun test开发观察模式：
bun run dev要在更改后重建，请执行以下操作：
bun run build可用的MCP工具
搜索问题
使用JQL搜索JIRA问题。每个请求最多返回50个结果。
输入架构：
{
searchString: string; // JQL search string
}获取图片_儿童
在史诗中获取所有儿童问题，包括他们的评论和关系数据。每个请求仅限100个问题。
输入架构：
{
epicKey: string; // The key of the epic issue
}获取问题
获取有关特定JIRA问题的详细信息，包括评论和所有关系。
输入架构：
{
issueId: string; // The ID or key of the JIRA issue
}创建_发行
使用指定字段创建新的JIRA问题。
输入架构：
{
projectKey: string, // The project key where the issue will be created
issueType: string, // The type of issue (e.g., "Bug", "Story", "Task")
summary: string, // The issue summary/title
description?: string, // Optional issue description
fields?: { // Optional additional fields
[key: string]: any
}
}update_issue
更新现有JIRA问题的字段。
输入架构：
{
issueKey: string, // The key of the issue to update
fields: { // Fields to update
[key: string]: any
}
}添加附件
向JIRA问题添加文件附件。
输入架构：
{
issueKey: string, // The key of the issue
fileContent: string, // Base64 encoded file content
filename: string // Name of the file to be attached
}添加注释
为JIRA问题添加评论。接受纯文本并在内部将其转换为所需的Atlassian文档格式。
输入架构：
{
issueIdOrKey: string, // The ID or key of the issue to add the comment to
body: string // The content of the comment (plain text)
}数据清理功能
- 从Atlassian文档格式中提取文本
- 跟踪描述和评论中提到的问题
- 与关系类型保持正式的问题联系
- 维护父母/子女关系
- 追踪史诗般的联想
- 包括评论历史记录和作者信息
- 从响应中删除不必要的元数据
- 递归处理提及内容节点
- 重复问题提及
技术细节
- 在严格模式下使用TypeScript构建
- 使用Bun运行时提高性能
- Vite用于优化构建
- 双重运输支持：
- 工作室：适用于Claude Desktop和Cline（默认） - 可流式HTTP（MCP 2025-03-26）：适用于MCP Inspector v0.15.x+和邮递员MCP客户端
- 具有自动清理功能的会话管理（1小时到期）
- 基于UUID的会话跟踪
Mcp-Session-Id标头 - 使用JIRA REST API v3（云）或v2（服务器/数据中心）
- 支持多种身份验证方法：
- 使用API令牌或用户名/密码进行基本身份验证 - 使用个人访问令牌（PAT）进行承载身份验证
- API对相关数据的批量请求
- 优化了AI上下文窗口的响应有效载荷
- 复杂Atlassian结构的高效转换
- 稳健的错误处理
- 利率限制考虑因素
- 最大限制：
- 搜索结果：每个请求50个问题 - 史诗儿童：每项请求100个问题
- 支持安全文件附件的多部分表单数据
- 自动内容类型检测和验证
- 在HTTP模式下为跨源请求启用CORS
错误处理
服务器实施了全面的错误处理策略：
- 网络错误检测和适当的消息传递
- HTTP状态码处理（尤其是404问题）
- 带有状态代码的详细错误消息
- 将错误详细信息记录到控制台
- 所有参数的输入验证
- 通过MCP协议进行安全错误传播
- 针对常见JIRA API错误的专门处理
- 附件的Base64验证
- 多部分请求失败处理
- 速率限制检测
- 附件参数验证
运输方式比较
| 功能 | STDIO传输 | 可流式HTTP传输 |
|---|---|---|
| 用例 | Claude Desktop，Cline | MCP检查员，邮递员，HTTP客户端 |
| 协议 | MCP over stdio | MCP可流式HTTP（2025-03-26） |
| 配置 | MCP配置文件 | 环境变量 |
| 连接 | 进程stdin/stdout | HTTP+服务器发送事件 |
| 默认端口 | 无 | 3000 |
| 会话管理 | N/A | 是（基于UUID，1小时到期） |
| 端点 | N/A | 获取/发布/删除 /mcp |
| CORS支持 | N/A | 是 |
| 健康检查 | 否 | 是(/health 端点） |
| 最适合 | 生产人工智能助手 | 开发、测试、调试 |
| 检查器兼容性 | 不适用 | v0.15.x+ |
手动测试
这 tests/manual/ 目录包含全面的测试脚本：
test_sse.sh-测试SSE连接和会话建立test_initialize.sh-测试初始化握手test_tools_list.sh-测试工具/列表请求test_tool_execution.sh-测试工具执行（搜索问题）postman_collection.json-完成Postman测试集README.md-详细的测试说明
运行所有测试：
cd tests/manual
./test_sse.sh
./test_initialize.sh
./test_tools_list.sh
./test_tool_execution.sh许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。