Jira MCP Server

🚀 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 問題跟蹤器。