使用说明

Jira MCP服务器

一个全面的、生产就绪的模型上下文协议（MCP）服务器，用于无缝集成Jira Cloud。此增强版本为AI代理、自动化系统和自定义应用程序提供了高级功能、强大的错误处理和广泛的工具。

🚀 特性

核心功能

董事会管理：列出、过滤和管理包含详细信息的Jira板
问题操作：全面创建、更新、搜索、转换和管理问题
用户管理：搜索用户、获取用户详细信息和管理分配
项目管理：查看项目，获取详细的项目信息
时间跟踪：添加和查看具有灵活时间格式的工作日志
评论系统：添加支持富格文本的注释（ADF格式）
服务器信息：监视服务器状态和运行状况

增强功能

速率限制：智能API请求节流以遵守Jira限制
综合录井：可配置的多级日志记录
错误处理：具有详细错误消息的稳健错误处理
输入验证：彻底验证环境变量和输入
模块化架构：具有基于服务的架构的干净、可维护的代码库
TypeScript支持：具有全面类型定义的完整TypeScript实现
丰富的格式：漂亮的标记表和格式化的响应
高级搜索：通过有用的示例支持复杂的JQL查询

🛠️ 需求

Node.js：18.0.0或更高
吉拉云：访问Jira Cloud实例
API代币：Jira API代币(在此处创建)

⚙️ 环境变量

创建一个 .env 文件或设置这些环境变量：

JIRA_BASE_URL=https://your-company.atlassian.net
JIRA_EMAIL=your-email@company.com
JIRA_API_TOKEN=your-jira-api-token
LOG_LEVEL=INFO  # Optional: ERROR, WARN, INFO, DEBUG

🚀 快速开始

选项1：使用npx（推荐）

# Run directly without installation
npx @orengrinker/jira-mcp-server

# With environment variables
JIRA_BASE_URL=https://company.atlassian.net \
JIRA_EMAIL=user@company.com \
JIRA_API_TOKEN=your-token \
npx @orengrinker/jira-mcp-server

选项2:Claude桌面配置

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["@orengrinker/jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-company.atlassian.net",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

选项3：全局安装

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

方案4：地方发展

git clone https://github.com/OrenGrinker/jira-mcp-server.git
cd jira-mcp-server
npm install
npm run build
node dist/index.js

🧰 可用工具

电路板工具

get_boards -按类型和项目列出所有具有可选过滤功能的电路板
get_board_details -获取全面的董事会信息
get_board_issues -使用高级过滤选项解决电路板问题

问题工具

search_issues -使用具有灵活参数的JQL搜索问题
get_issue_details -获取全面的问题信息
create_issue -在全面的现场支持下创建新问题
update_issue -更新现有问题
transition_issue -在状态之间移动问题
add_comment -添加支持富格文本的评论

用户工具

get_current_user -获取经过身份验证的用户信息
search_users -按姓名、电子邮件或用户名查找用户
get_user_details -获取详细的用户信息

项目工具

get_projects -列出所有可访问的项目
get_project_details -获取全面的项目信息

时间跟踪工具

add_worklog -以灵活的格式记录工作时间
get_worklogs -查看问题的工作日志

系统工具

get_server_info -获取服务器状态和信息

💡 使用示例

Claude的自然语言命令

一旦配置了Claude Desktop，您就可以使用自然语言命令：

"Show me all my open issues in high priority"
"Create a new bug in PROJECT-X about login issues"
"Move ticket ABC-123 to In Progress"
"Log 2 hours of work on ABC-456 for code review"
"Add a comment to ABC-789 saying the fix is deployed"
"Show me all Scrum boards for the mobile project"
"Get details for issue ABC-100 including comments and worklogs"
"List all projects I have access to"

与MCP检查器一起使用

# List all boards
npx @modelcontextprotocol/inspector \
  npx @orengrinker/jira-mcp-server \
  get_boards

# Search for your issues
npx @modelcontextprotocol/inspector \
  npx @orengrinker/jira-mcp-server \
  search_issues \
  '{"jql": "assignee=currentUser() AND status!=Done"}'

# Create a new issue
npx @modelcontextprotocol/inspector \
  npx @orengrinker/jira-mcp-server \
  create_issue \
  '{"projectKey": "PROJ", "issueType": "Task", "summary": "New task from MCP"}'

JQL查询示例

# Your open issues
assignee = currentUser() AND status != Done

# Recent issues in a project
project = "MYPROJ" AND created >= -7d

# High priority bugs
priority = High AND issuetype = Bug

# Issues due this week
duedate >= startOfWeek() AND duedate <= endOfWeek()

# Unassigned issues in current sprint
assignee is EMPTY AND sprint in openSprints()

# Issues updated in the last 24 hours
updated >= -1d

# Epic issues with their child stories
"Epic Link" = PROJ-123 OR parent = PROJ-123

🔧 配置

获取Jira API代币

首选 Atlassian帐户设置
点击“创建API令牌”
给它一个描述性的名称（例如“MCP服务器”）
复制生成的令牌
在环境变量中使用它

需要权限

您的Jira用户应该具有：

浏览项目权限
创建问题权限（用于创建问题）
编辑问题权限（用于更新和转换）
问题许可工作（用于工作日志）
添加评论权限

🏗️ 发展

设置

git clone https://github.com/OrenGrinker/jira-mcp-server.git
cd jira-mcp-server
npm install

开发脚本

npm run dev          # Start development server with hot reload
npm run build        # Build for production
npm run clean        # Clean build directory
npm run start        # Start production server
npm run test         # Run tests (when available)

项目结构

src/
├── index.ts              # Main server entry point
├── jiraApiClient.ts      # Enhanced API client
├── toolRegistry.ts       # Tool registration and routing
├── types/
│   └── index.ts         # TypeScript type definitions
├── services/
│   ├── index.ts         # Service exports
│   ├── boardService.ts  # Board operations
│   ├── issueService.ts  # Issue operations
│   ├── userService.ts   # User operations
│   ├── projectService.ts # Project operations
│   ├── worklogService.ts # Worklog operations
│   └── serverService.ts  # Server operations
└── utils/
    ├── logger.ts        # Logging utility
    ├── rateLimiter.ts   # Rate limiting
    ├── validation.ts    # Input validation
    └── formatters.ts    # Response formatting

🔍 故障排除

常见问题

认证失败
- 验证您的API令牌和电子邮件是否正确
- 检查您的Jira基本URL是否正确（对于云，应以.atlassian.net结尾）
- 确保您的API令牌尚未过期
权限不足
- 验证您的Jira用户是否具有所需的权限
- 检查特定操作的项目级权限
网络错误
- 验证您的Jira基本URL是否可访问
- 检查防火墙和代理设置
- 确保您正在使用HTTPS
速率限制
- 服务器包括内置的速率限制
- 如果达到Jira的速率限制，请等待并重试
- 考虑减少并发请求

调试模式

启用调试日志记录：

export LOG_LEVEL=DEBUG

🧪 测试

# Test the server connection
JIRA_BASE_URL=https://your-company.atlassian.net \
JIRA_EMAIL=your@email.com \
JIRA_API_TOKEN=your-token \
node dist/index.js

🤝 贡献

我们欢迎捐款！请遵循以下指南：

分叉存储库
创建要素分支: git checkout -b feature/amazing-feature
进行更改 遵循我们的编码标准
添加测试 对于新功能
运行构建: npm run build
提交更改: git commit -m 'Add amazing feature'
推送到分支: git push origin feature/amazing-feature
打开拉取请求

编码标准

遵循TypeScript的最佳实践
使用有意义的变量和函数名
为公共API添加JSDoc注释
遵循常规提交消息
确保所有构建都通过

📊 演出

速率限制：内置速率限制尊重Jira API限制
连接池：高效的HTTP连接管理
错误恢复：瞬态故障的自动重试逻辑
内存效率高：大型数据集的流式响应

🔐 安全

无凭据存储：仅使用环境变量
输入验证：所有输入都经过验证和消毒
安全默认值：遵循安全最佳实践
审计跟踪：用于调试的全面日志记录

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🔗 链接

GitHub存储库: https://github.com/OrenGrinker/jira-mcp-server
NPM包: @orengrinker/jira mcp服务器
Jira Cloud REST API: 文档
模型上下文协议: 规格说明
创建API令牌: Atlassian指南

🆘 支持

问题: GitHub问题
文档：查看此README和内联代码文档
功能请求：打开带有“增强”标签的问题

🏆 致谢

与模型上下文协议SDK
受到MCP社区和最佳实践的启发
感谢所有提供反馈的贡献者和用户