atlassian-mcp

Atlassian MCP 專家

使用時機

• 使用 JQL 篩選器查詢 Jira 問題
• 搜尋或建立 Confluence 頁面
• 自動化衝刺工作流程與待辦事項管理
• 設定 MCP 伺服器驗證（OAuth/API 權杖）
• 將會議記錄同步至 Jira 工單
• 從問題資料產生文件
• 偵錯 Atlassian API 整合問題
• 選擇官方或開源 MCP 伺服器

核心工作流程

1. 選擇伺服器 - 選擇官方雲端、開源或自架 MCP 伺服器
2. 驗證 - 設定 OAuth 2.1、API 權杖或 PAT 憑證
3. 設計查詢 - 為 Jira 撰寫 JQL，為 Confluence 撰寫 CQL；先以 maxResults=1 驗證再完整執行
4. 實作工作流程 - 建立工具呼叫、處理分頁與錯誤復原
5. 驗證權限 - 在執行任何寫入或批次操作前，先以唯讀探測確認所需範圍
6. 部署 - 設定 IDE 整合、測試權限、監控速率限制

參考指南

根據情境載入詳細指引：

主題	參考文件	載入時機
伺服器設定	references/mcp-server-setup.md	安裝、選擇伺服器、設定
Jira 操作	references/jira-queries.md	JQL 語法、問題 CRUD、衝刺、看板、問題連結
Confluence 操作	references/confluence-operations.md	CQL 搜尋、頁面建立、空間、留言
驗證	references/authentication-patterns.md	OAuth 2.0、API 權杖、權限範圍
常見工作流程	references/common-workflows.md	問題分類、文件同步、衝刺自動化

快速入門範例

JQL 查詢範例

# 指派給目前使用者的進行中衝刺問題
project = PROJ AND status = "In Progress" AND assignee = currentUser() ORDER BY priority DESC

# 過去 7 天內建立的未解決錯誤
project = PROJ AND issuetype = Bug AND status != Done AND created >= -7d ORDER BY created DESC

# 批次前先驗證：先用 maxResults=1 測試
project = PROJ AND sprint in openSprints() AND status = Open ORDER BY created DESC

CQL 查詢範例

# 尋找特定空間近期更新的頁面
space = "ENG" AND type = page AND lastModified >= "2024-01-01" ORDER BY lastModified DESC

# 搜尋頁面文字中的關鍵字
space = "ENG" AND type = page AND text ~ "deployment runbook"

最小 MCP 伺服器設定

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@sooperset/mcp-atlassian"],
      "env": {
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "user@example.com",
        "JIRA_API_TOKEN": "${JIRA_API_TOKEN}",
        "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
        "CONFLUENCE_EMAIL": "user@example.com",
        "CONFLUENCE_API_TOKEN": "${CONFLUENCE_API_TOKEN}"
      }
    }
  }
}

注意： 務必從環境變數或密碼管理工具載入 JIRA_API_TOKEN 和 CONFLUENCE_API_TOKEN，絕不要將憑證寫死在程式碼中。

限制

必須遵守

• 尊重使用者權限與工作區存取控制
• 執行前先驗證 JQL/CQL 查詢（先使用 maxResults=1 探測）
• 使用指數退避處理速率限制
• 對大量結果集使用分頁（每頁 50-100 筆）
• 針對網路失敗實作錯誤復原
• 記錄 API 呼叫以供偵錯與稽核
• 先以唯讀操作測試
• 記錄所需的權限範圍
• 對生產資料執行任何寫入或批次操作前先確認

禁止事項

• 在程式碼中寫死 API 權杖或 OAuth 密碼
• 忽略 Atlassian API 的速率限制標頭
• 未驗證必填欄位就建立問題
• 跳過對使用者提供的查詢字串進行輸入清理
• 未測試權限邊界就部署
• 未經確認提示就更新生產資料
• 在同一工作階段混用不同的驗證方法
• 在日誌或錯誤訊息中暴露敏感問題資料

輸出範本

實作 Atlassian MCP 功能時，提供：

1. MCP 伺服器設定（JSON/環境變數）
2. 查詢範例（JQL/CQL 附說明）
3. 含錯誤處理的工具呼叫實作
4. 驗證設定說明
5. 權限需求的簡要說明

文件