STARWARCLOUD STARWAR.AI
返回市场
Jira-MCP-服务器

Jira-MCP-服务器

作者：OrenGrinker2 星标更新：2025-06-22
安装使用来源：spider==github.com

项目介绍

Jira MCP Server

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

🚀 功能

核心功能

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

增强功能

  • 速率限制：智能API请求节流以尊重Jira限制
  • 全面日志记录：可配置的日志记录，具有多个级别
  • 错误处理：强大的错误处理，带有详细的错误消息
  • 输入验证：对环境变量和输入进行彻底验证
  • 模块化架构：干净、易于维护的服务架构代码库
  • TypeScript支持：完整的TypeScript实现，带有全面的类型定义
  • 丰富的格式：漂亮的markdown表格和格式化的响应
  • 高级搜索：支持复杂的JQL查询，并提供有用的示例

🛠️ 要求

  • Node.js：18.0.0或更高版本
  • Jira Cloud：访问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  # 可选：ERROR, WARN, INFO, DEBUG

🚀 快速开始

选项1：使用npx（推荐）

# 直接运行而无需安装
npx @orengrinker/jira-mcp-server

# 使用环境变量
JIRA_BASE_URL=https://company.atlassian.net \
JIRA_EMAIL=user@company.com \
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": "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配置好，你可以使用自然语言命令：

"显示我所有高优先级的未解决问题"
"在PROJECT-X中创建一个新的关于登录问题的bug"
"将票证ABC-123移到进行中"
"记录2小时的代码审查工作时间在ABC-456上"
"向ABC-789添加一条评论说修复已部署"
"显示移动项目的Scrum看板"
"获取问题ABC-100的详细信息，包括评论和工作日志"
"列出我有访问权限的所有项目"

使用MCP Inspector

# 列出所有看板
npx @modelcontextprotocol/inspector \
  npx @orengrinker/jira-mcp-server \
  get_boards

# 搜索你的问题
npx @modelcontextprotocol/inspector \
  npx @orengrinker/jira-mcp-server \
  search_issues \
  '{"jql": "assignee=currentUser() AND status!=Done"}'

# 创建新问题
npx @modelcontextprotocol/inspector \
  npx @orengrinker/jira-mcp-server \
  create_issue \
  '{"projectKey": "PROJ", "issueType": "Task", "summary": "从MCP的新任务"}'

JQL查询示例

# 你的未解决问题
assignee = currentUser() AND status != Done

# 项目中的最近问题
project = "MYPROJ" AND created >= -7d

# 高优先级的bug
priority = High AND issuetype = Bug

# 本周到期的问题
duedate >= startOfWeek() AND duedate <= endOfWeek()

# 当前冲刺中的未分配问题
assignee is EMPTY AND sprint in openSprints()

# 最近24小时内更新的问题
updated >= -1d

# 关联Epic的问题及其子故事
"Epic Link" = PROJ-123 OR parent = PROJ-123

🔧 配置

获取你的Jira API令牌

  1. 前往Atlassian账户设置
  2. 点击“创建API令牌”
  3. 给它一个描述性名称（例如，“MCP Server”）
  4. 复制生成的令牌
  5. 在你的环境变量中使用它

所需权限

你的Jira用户应具备：

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

🏗️ 开发

设置

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

开发脚本

npm run dev          # 启动带有热重载的开发服务器
npm run build        # 构建生产环境
npm run clean        # 清除构建目录
npm run start        # 启动生产服务器
npm run test         # 运行测试（当可用时）

项目结构

src/
├── index.ts              # 主服务器入口点
├── jiraApiClient.ts      # 增强的API客户端
├── toolRegistry.ts       # 工具注册和路由
├── types/
│   └── index.ts         # TypeScript类型定义
├── services/
│   ├── index.ts         # 服务导出
│   ├── boardService.ts  # 看板操作
│   ├── issueService.ts  # 问题操作
│   ├── userService.ts   # 用户操作
│   ├── projectService.ts # 项目操作
│   ├── worklogService.ts # 工作日志操作
│   └── serverService.ts  # 服务器操作
└── utils/
    ├── logger.ts        # 日志实用程序
    ├── rateLimiter.ts   # 速率限制
    ├── validation.ts    # 输入验证
    └── formatters.ts    # 响应格式化

🔍 故障排除

常见问题

  1. 身份验证失败

    • 验证你的API令牌和电子邮件是否正确
    • 检查你的Jira基础URL是否正确（对于云服务应以.atlassian.net结尾）
    • 确保你的API令牌没有过期

  2. 权限被拒绝

    • 验证你的Jira用户是否有必要的权限
    • 检查特定操作的项目级权限

  3. 网络错误

    • 验证你的Jira基础URL是否可访问
    • 检查防火墙和代理设置
    • 确保你正在使用HTTPS

  4. 速率限制

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

调试模式

启用调试日志记录：

export LOG_LEVEL=DEBUG

🧪 测试

# 测试服务器连接
JIRA_BASE_URL=https://your-company.atlassian.net \
JIRA_EMAIL=your@email.com \
JIRA_API_TOKEN=your-token \
node dist/index.js

🤝 贡献

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

  1. 分叉仓库
  2. 创建特性分支：git checkout -b feature/amazing-feature
  3. 按照我们的编码标准进行更改
  4. 为新功能添加测试
  5. 运行构建：npm run build
  6. 提交更改：git commit -m '添加惊人的功能'
  7. 推送到分支：git push origin feature/amazing-feature
  8. 打开拉取请求

编码标准

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

📊 性能

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

🔐 安全

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

📄 许可

本项目根据MIT许可发布 - 详见LICENSE文件。

🔗 链接

🆘 支持

  • 问题：GitHub问题
  • 文档：检查此README和内联代码文档
  • 功能请求：使用“enhancement”标签打开一个问题

🏆 致谢