Jira MCP服务器
一个全面的、生产就绪的模型上下文协议(MCP)服务器,用于无缝集成Jira Cloud。此增强版本为AI代理、自动化系统和自定义应用程序提供了高级功能、强大的错误处理和广泛的工具。
> 备注这是一把叉子 @orengrinker/jira mcp服务器 进行自定义修改。Oren Grinker的原创作品。
🚀 特性
核心功能
- 董事会管理:列出、过滤和管理包含详细信息的Jira板
- 问题操作:全面创建、更新、搜索、转换和管理问题
- 用户管理:搜索用户、获取用户详细信息和管理分配
- 项目管理:查看项目,获取详细的项目信息
- 时间跟踪:添加和查看具有灵活时间格式的工作日志
- 评论系统:添加支持富格文本的注释(ADF格式)
- 服务器信息:监视服务器状态和运行状况
增强功能
- ⚡️ 性能优化:使用单个请求分组结果优化问题检索(速度快5-6倍)
- 速率限制:智能API请求节流以遵守Jira限制
- 综合录井:可配置的多级日志记录
- 错误处理:具有详细错误消息的稳健错误处理
- 输入验证:彻底验证环境变量和输入
- 模块化架构:具有基于服务的架构的干净、可维护的代码库
- TypeScript支持:具有全面类型定义的完整TypeScript实现
- 丰富的格式:漂亮的标记表和带有直接Jira链接的格式化响应
- 高级搜索:通过有用的示例支持复杂的JQL查询
- AI驱动的工作流程:自动工作流处理和人工智能生成的问题解决方案
- 问题跟踪:针对情境感知操作的智能问题跟踪
🛠️ 需求
- Node.js:18.0.0或更高
- 吉拉云:访问Jira Cloud实例
- API代币:Jira API代币(在此处创建)
⚙️ 环境变量
创建一个 .env 文件或设置这些环境变量:```bash
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(推荐)```bash
# 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:```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:全局安装```bash
npm install -g @orengrinker/jira-mcp-server
jira-mcp-server
方案4:地方发展```bash
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` -使用高级过滤选项解决电路板问题
### 问题工具
- **`get_my_issues_grouped`** ⚡️ **新的和优化的** -将您的未决问题按状态分组到一个请求中(比其他选项快5-6倍)
- `search_issues` -使用具有灵活参数的JQL搜索问题
- `get_issue_details` -获取全面的问题信息
- `create_issue` -在全面的现场支持下创建新问题
- `update_issue` -更新现有问题
- `transition_issue` -在状态之间移动问题
- `add_comment` -添加支持富格文本的评论
- `complete_issue` -通过人工智能生成的解决方案和工作流处理来解决/完成问题
### 用户工具
- `get_current_user` -获取经过身份验证的用户信息
- `search_users` -按姓名、电子邮件或用户名查找用户
- `get_user_details` -获取详细的用户信息
### 项目工具
- `get_projects` -列出所有可访问的项目
- `get_project_details` -获取全面的项目信息
### 时间跟踪工具
- `add_worklog` -以灵活的格式记录工作时间
- `get_worklogs` -查看问题的工作日志
### 系统工具
- `get_server_info` -获取服务器状态和信息
## 💡 用法示例
### 使用Claude或Cursor的自然语言命令
一旦配置了Claude Desktop或Cursor,您就可以使用自然语言命令:```
"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"
"Close issue ABC-123" or "Complete ABC-123"
⚡️ 优化问题查看(推荐)
为了在查看任务时获得最佳性能,请使用优化的分组视图:```
In Claude or Cursor
"/jira" # Shows all your open issues grouped by status
This uses get_my_issues_grouped which:
- Makes only 1 API request (vs 6+ with traditional methods)
- Groups issues by status automatically
- Provides direct links to Jira
- Shows quick action menu
- 5-6x faster response time
有关Cursor中的详细设置说明,请参阅:
- **快速开始**: `CURSOR_QUICK_START.md`
- **完整提示**: `CURSOR_JIRA_PROMPT.md`
### 与MCP检查器一起使用```bash
# 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查询示例```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代币
1. 首选 Atlassian帐户设置
1. 点击“创建API令牌”
1. 给它一个描述性的名称(例如“MCP服务器”)
1. 复制生成的令牌
1. 在环境变量中使用它
### 需要权限
您的Jira用户应该具有:
- 浏览项目权限
- 创建问题权限(用于创建问题)
- 编辑问题权限(用于更新和转换)
- 问题许可工作(用于工作日志)
- 添加评论权限
## 🏗️ 发展
### 设置```bash
git clone https://github.com/OrenGrinker/jira-mcp-server.git
cd jira-mcp-server
npm install
开发脚本```bash
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的速率限制,请等待并重试
- 考虑减少并发请求
调试模式
默认情况下启用DEBUG日志记录 以帮助诊断问题。日志显示:
- 所有Jira API请求(URL、方法、参数)
- 响应状态和摘要(项目总数、计数)
- MCP工具执行(参数、结果预览)
- 错误跟踪和详细消息
要更改日志级别,请设置环境变量:```bash
export LOG_LEVEL=DEBUG # DEBUG, INFO, WARN, ERROR (default: DEBUG)
### MCP服务器日志
通过Cursor运行MCP服务器时,您可以在此处找到日志:
**macOS:**```bash
# View live MCP logs with DEBUG output
tail -f ~/Library/Application\ Support/Cursor/logs/*/window*/exthost/anysphere.cursor-mcp/MCP\ user-jira.log
# Or list all log directories
ls -lt ~/Library/Application\ Support/Cursor/logs/
窗户:```bash
%APPDATA%\Cursor\logs\
**Linux:**```bash
~/.config/Cursor/logs/
调试输出示例:```
[DEBUG] [JiraApiClient] Making GET request to: https://job.sbertroika.ru/rest/api/2/search?jql=...
[DEBUG] [JiraApiClient] Response status: 200 OK
[DEBUG] [JiraApiClient] Response summary: { total: 176, issuesCount: 176 }
[DEBUG] [JiraMCPServer] MCP result sent to Cursor: { type: 'text', textLength: 15521 }
日志包括:
- **连接状态** 以及身份验证详细信息
- **API请求** 包含完整的URL和参数
- **API响应** 带有状态代码和数据摘要
- **MCP协议** 消息和工具执行流程
- **错误痕迹** 具有详细的上下文
## 🧪 测试
### 使用Make命令
该项目包括一个全面的 `Makefile` 为了便于测试:```bash
# Show all available commands
make help
# Run all tests
make test-all
# Test specific functionality
make test-grouped # Test get_my_issues_grouped (preview)
make test-grouped-full # Test get_my_issues_grouped (full output)
make test-priorities # Check Jira priorities
make test-current-user # Get current user info
make test-my-issues # Test search_issues
# Test specific issue
make test-issue-detail ISSUE_KEY=RIVER-123
# Test user search
make test-search-users QUERY=Агафонов
# View logs
make logs # Real-time log viewing
make logs-errors # Show only errors
# Development
make build # Build project
make lint # Run linter
make format # Format code
make typecheck # Type checking
手动测试```bash
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注释
- 遵循常规提交消息
- 确保所有构建都通过
📊 演出
- ⚡️ 优化问题检索新
get_my_issues_grouped函数将API调用从6个减少到1个(速度快5-6倍) - 速率限制:内置速率限制尊重Jira API限制
- 连接池:高效的HTTP连接管理
- 错误恢复:瞬态故障的自动重试逻辑
- 内存效率高:大型数据集的流式响应
性能比较
| 操作 | 传统方法 | 优化方法 | 改进 |
|---|---|---|---|
| 查看我的任务 | 6个请求(~3-5s) | 1个请求(~0.5-1s) | 速度快5-6倍 ⚡️ |
| 查看任务详细信息 | 1请求 | 1请求 | 相同 |
| 完成任务 | 1-3个请求 | 1-1个请求(自动工作流) | 相同+AI分辨率 |
🔐 安全
- 无凭据存储:仅使用环境变量
- 输入验证:所有输入都经过验证和消毒
- 安全默认值:遵循安全最佳实践
- 审计跟踪:用于调试的全面日志记录
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🔗 链接
- GitHub存储库: https://github.com/OrenGrinker/jira-mcp-server
- NPM包: @orengrinker/jira mcp服务器
- Jira Cloud REST API: 文档
- 模型上下文协议: 规格说明
- 创建API令牌: Atlassian指南
🆘 支持
- 问题: GitHub问题
- 文档:查看此README和内联代码文档
- 功能请求:打开带有“增强”标签的问题
🏆 致谢
- 与 模型上下文协议SDK
- 受到MCP社区和最佳实践的启发
- 感谢所有提供反馈的贡献者和用户
