Jira Mcp Server

Jira MCP 服务

一款功能全面、适用于生产环境的 Model Context Protocol (MCP) 服务，可无缝集成 Jira Cloud。此增强版本为 AI Agent、自动化系统和自定义应用提供高级功能、可靠的错误处理和丰富的工具。

🚀 功能

核心功能

• 看板管理：列出、筛选和管理 Jira 看板，并提供详细信息
• 问题操作：全面创建、更新、搜索、转换和管理问题
• 用户管理：搜索用户、获取用户详情并管理任务分配
• 项目管理：查看项目并获取详细的项目信息
• 时间跟踪：使用灵活的时间格式添加和查看工作日志
• 评论系统：添加支持富文本的评论（ADF 格式）
• 服务信息：监控服务状态和运行状况

增强功能

• 速率限制：智能限制 API 请求频率，遵守 Jira 限制
• 全面日志记录：支持多个级别的可配置日志记录
• 错误处理：可靠的错误处理，并提供详细的错误消息
• 输入验证：全面验证环境变量和输入内容
• 模块化架构：采用基于服务的架构，代码库清晰且易于维护
• TypeScript 支持：完整的 TypeScript 实现，并提供全面的类型定义
• 丰富的格式：美观的 Markdown 表格和格式化响应
• 高级搜索：支持复杂的 JQL 查询，并提供实用示例

🛠️ 要求

• Node.js：18.0.0 或更高版本
• Jira Cloud：可访问 Jira Cloud 实例
• API Token：Jira API Token（在此创建）

⚙️ 环境变量

创建 .env 文件或设置以下环境变量：

JIRA_BASE_URL=https://your-company.atlassian.net
[email protected]
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 \
[email protected] \
JIRA_API_TOKEN=your-token \
npx @orengrinker/jira-mcp-server

选项 2：Claude Desktop 配置

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["@orengrinker/jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-company.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "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 Inspector 搭配使用

# 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 Token

1. 前往 Atlassian 账户设置
2. 点击“Create API token”
3. 为其指定一个描述性名称（例如，“MCP Server”）
4. 复制生成的 Token
5. 在环境变量中使用该 Token

所需权限

你的 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

🔍 故障排除

常见问题

1. 身份验证失败

   • 确认 API 令牌和电子邮件地址正确
   • 检查 Jira 基础 URL 是否正确（云端服务的 URL 应以 .atlassian.net 结尾）
   • 确认 API 令牌尚未过期

2. 权限被拒绝

   • 确认 Jira 用户拥有所需权限
   • 检查特定操作所需的项目级权限

3. 网络错误

   • 确认 Jira 基础 URL 可以访问
   • 检查防火墙和代理设置
   • 确认使用的是 HTTPS

4. 速率限制

   • 服务内置了速率限制
   • 如果触发了 Jira 的速率限制，请等待后重试
   • 考虑减少并发请求

调试模式

启用调试日志：

export LOG_LEVEL=DEBUG

🧪 测试

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

🤝 贡献

欢迎贡献！请遵循以下指南：

1. Fork 仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 按照我们的编码标准进行修改
4. 为新功能添加测试
5. 运行构建：npm run build
6. 提交更改：git commit -m 'Add amazing feature'
7. 推送到分支：git push origin feature/amazing-feature
8. 创建 Pull Request

编码标准

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

📊 性能

• 速率限制：内置速率限制遵循 Jira API 限制
• 连接池：高效管理 HTTP 连接
• 错误恢复：针对暂时性故障自动重试
• 内存效率：对大型数据集使用流式响应

🔐 安全

• 不存储凭证：仅使用环境变量
• 输入验证：验证并清理所有输入
• 安全默认设置：遵循安全最佳实践
• 审计跟踪：提供全面的日志以便调试

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🔗 链接

• GitHub 仓库：https://github.com/OrenGrinker/jira-mcp-server
• NPM 包：@orengrinker/jira-mcp-server
• Jira Cloud REST API：文档
• Model Context Protocol：规范
• 创建 API 令牌：Atlassian 指南

🆘 支持

• 问题：GitHub Issues
• 文档：请参阅此 README 和内联代码文档
• 功能请求：使用 “enhancement” 标签创建 issue

🏆 致谢

• 使用 Model Context Protocol SDK 构建
• 灵感来自 MCP 社区和最佳实践
• 感谢所有贡献者和提供反馈的用户