Jira MCP Server

🚀 Jira MCP Server

这是一个用于与 Jira 集成的模型上下文协议（MCP）服务器。该服务器使 Claude 等 AI 助手能够与 Jira Cloud 实例进行交互。

✨ 主要特性

• 🎫 问题管理（创建、读取、更新、搜索）
• 📋 项目列表展示
• 🔍 JQL 搜索功能
• 🔐 API 令牌认证
• 📝 使用 TypeScript 实现
• 🖥️ 跨平台支持（Windows、macOS、Linux）

📦 安装指南

系统要求

• Node.js 18.x 或更高版本
• npm 或 yarn
• Jira Cloud 实例（不适用于 Jira Server/Data Center）

安装步骤

1. 执行以下命令进行安装：

npm install

2. 在项目根目录创建一个 .env 文件，并按如下示例配置：

JIRA_HOST=your-domain.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your-api-token-here

3. 生成 API 令牌
   1. 访问 Atlassian 账户设置。
   2. 点击“创建 API 令牌”。
   3. 为令牌添加有意义的标签。
   4. 将生成的令牌复制到 .env 文件中。
4. 构建并运行项目：

npm run build
npm start

💻 使用示例

基础用法

创建问题

{
  "projectKey": "PROJ",
  "summary": "Fix login bug",
  "description": "Users cannot log in with special characters in password",
  "issueType": "Bug"
}

搜索问题

{
  "jql": "project = PROJ AND status = \"In Progress\" AND assignee = currentUser()",
  "maxResults": 20
}

获取问题详情

{
  "issueKey": "PROJ-123"
}

高级用法

为 Claude Desktop 配置

在 Claude Desktop MCP 配置中添加以下内容：

macOS/Linux

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/jira-mcp-server/build/index.js"],
      "env": {
        "JIRA_HOST": "your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Windows

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["C:\\path\\to\\jira-mcp-server\\build\\index.js"],
      "env": {
        "JIRA_HOST": "your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

📚 详细文档

可用工具

问题管理

• jira_create_issue - 创建新问题
• jira_get_issue - 获取详细的问题信息
• jira_update_issue - 更新问题字段
• jira_search_issues - 使用 JQL 搜索问题
• jira_list_projects - 列出所有可访问的项目

认证方式

使用电子邮件 + API 令牌进行基本认证。这是 Jira Cloud 最安全的认证方法。

错误处理

服务器包含全面的错误处理机制，可处理以下情况：

• 无效的凭证
• 网络超时
• 无效的 JQL 查询
• 缺少权限
• 不存在的资源

所有错误都以结构化格式返回，并附带有用的错误信息。

开发相关

构建项目

npm run build

测试项目

# 测试服务器
node build/index.js

故障排除

常见问题

1. 服务器无法启动：
   • 检查 .env 文件是否正确配置。
   • 验证 API 令牌是否有效。
   • 确保 Node.js 版本为 18 或更高。
2. 权限错误：
   • 验证 Jira 用户是否具有适当的权限。
   • 检查项目密钥是否存在且可访问。
3. 连接问题：
   • 验证 Jira 主机 URL 是否正确。
   • 检查与 Jira Cloud 的网络连接。

📄 许可证

ISC

贡献说明

有关如何为该项目做出贡献的详细信息，请参阅 CONTRIBUTING.md。

支持与反馈

如有问题或功能请求，请使用 GitHub 问题跟踪器。