MCP-Atlassian 項目詳細介紹

項目概述

MCP-Atlassian 是一個基於 Model Context Protocol (MCP) 的伺服器，專為 Atlassian 產品（Confluence 和 Jira）設計。該項目允許 AI 助手（如 Claude）直接訪問和操作您的 Atlassian 工作空間數據，實現智能化的工作流程管理。

項目基本資訊

• 項目名稱: mcp-atlassian
• 開發者: sooperset
• GitHub地址: https://github.com/sooperset/mcp-atlassian
• 部署方式: Docker 容器

核心功能特性

AI 驅動的智能操作

項目支持多種 AI 助手驅動的智能操作：

• 📝 自動 Jira 更新 - "從我們的會議記錄更新 Jira"
• 🔍 AI 驅動的 Confluence 搜索 - "在 Confluence 中找到我們的 OKR 指南並總結"
• 🐛 智能 Jira 問題過濾 - "顯示上週 PROJ 項目中的緊急 bug"
• 📄 內容創建與管理 - "為 XYZ 功能創建技術設計文檔"

產品兼容性支持

產品	部署類型	支持狀態
Confluence	Cloud	✅ 完全支持
Confluence	Server/Data Center	✅ 支持 (版本 6.0+)
Jira	Cloud	✅ 完全支持
Jira	Server/Data Center	✅ 支持 (版本 8.14+)

安裝與配置

前置要求

• Docker 環境
• Atlassian API Token（雲版）或個人訪問令牌（伺服器版）

獲取認證令牌

Atlassian Cloud:

1. 訪問 https://id.atlassian.com/manage-profile/security/api-tokens
2. 點擊 "Create API token"，命名並複製令牌

Server/Data Center:

1. 前往個人資料 → 個人訪問令牌
2. 點擊 "Create token"，設置到期時間並複製令牌

Docker 鏡像獲取

# 拉取預構建鏡像
docker pull ghcr.io/sooperset/mcp-atlassian:latest

IDE 集成配置

Claude Desktop 配置

配置文件位置：

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

方法1：直接傳遞變量

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_USERNAME", 
        "-e", "CONFLUENCE_API_TOKEN",
        "-e", "JIRA_URL",
        "-e", "JIRA_USERNAME",
        "-e", "JIRA_API_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_confluence_api_token",
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com", 
        "JIRA_API_TOKEN": "your_jira_api_token"
      }
    }
  }
}

方法2：使用環境文件

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm", 
        "-i",
        "--env-file",
        "/path/to/your/mcp-atlassian.env",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ]
    }
  }
}

Server/Data Center 配置

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i", 
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_PERSONAL_TOKEN",
        "-e", "CONFLUENCE_SSL_VERIFY",
        "-e", "JIRA_URL", 
        "-e", "JIRA_PERSONAL_TOKEN",
        "-e", "JIRA_SSL_VERIFY",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://confluence.your-company.com",
        "CONFLUENCE_PERSONAL_TOKEN": "your_confluence_pat",
        "CONFLUENCE_SSL_VERIFY": "false",
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_PERSONAL_TOKEN": "your_jira_pat", 
        "JIRA_SSL_VERIFY": "false"
      }
    }
  }
}

環境變量說明

常用環境變量：

• CONFLUENCE_SPACES_FILTER: 按空間鍵過濾 (例如: "DEV,TEAM,DOC")
• JIRA_PROJECTS_FILTER: 按項目鍵過濾 (例如: "PROJ,DEV,SUPPORT")
• READ_ONLY_MODE: 設置為 "true" 禁用寫操作
• MCP_VERBOSE: 設置為 "true" 啟用詳細日誌
• ENABLED_TOOLS: 逗號分隔的工具名稱列表

可用工具功能

Confluence 工具

工具名稱	功能描述
confluence_search	使用 CQL 搜索 Confluence 內容
confluence_get_page	獲取特定頁面內容
confluence_get_page_children	獲取頁面子頁面
confluence_get_page_ancestors	獲取頁面父級頁面
confluence_get_comments	獲取頁面評論
confluence_create_page	創建新頁面
confluence_update_page	更新現有頁面
confluence_delete_page	刪除頁面
confluence_get_labels	獲取標籤
confluence_add_label	添加標籤

Jira 工具

工具名稱	功能描述
jira_get_issue	獲取特定問題詳情
jira_search	使用 JQL 搜索問題
jira_get_project_issues	獲取項目問題
jira_get_epic_issues	獲取史詩問題
jira_create_issue	創建新問題
jira_batch_create_issues	批量創建問題
jira_update_issue	更新現有問題
jira_delete_issue	刪除問題
jira_get_transitions	獲取問題狀態轉換
jira_transition_issue	轉換問題狀態
jira_add_comment	添加評論
jira_add_worklog	添加工作日誌
jira_get_worklog	獲取工作日誌
jira_download_attachments	下載附件
jira_link_to_epic	鏈接到史詩
jira_get_agile_boards	獲取看板
jira_get_board_issues	獲取看板問題
jira_get_sprints_from_board	獲取看板衝刺
jira_get_sprint_issues	獲取衝刺問題
jira_create_sprint	創建衝刺
jira_update_sprint	更新衝刺
jira_get_issue_link_types	獲取問題鏈接類型
jira_create_issue_link	創建問題鏈接
jira_remove_issue_link	移除問題鏈接

注：標記為 * 的工具僅在 Jira Cloud 上可用

訪問控制

工具過濾

使用 --enabled-tools 標誌或 ENABLED_TOOLS 環境變量指定可用工具：

# 通過環境變量
ENABLED_TOOLS="confluence_search,jira_get_issue,jira_search"

# 或通過命令行標誌
docker run ... --enabled-tools "confluence_search,jira_get_issue,jira_search" ...

讀寫控制

工具分為讀取和寫入操作。啟用 READ_ONLY_MODE 時，無論 ENABLED_TOOLS 設置如何，僅讀取操作可用。

故障排除

常見問題解決

認證失敗:

• Cloud版：檢查 API 令牌（不是賬戶密碼）
• Server/Data Center版：驗證個人訪問令牌有效且未過期
• 舊版 Confluence 伺服器：可能需要使用 CONFLUENCE_USERNAME 和 CONFLUENCE_API_TOKEN（令牌為密碼）

SSL 證書問題: Server/Data Center 部署如遇 SSL 錯誤，設置 CONFLUENCE_SSL_VERIFY=false 或 JIRA_SSL_VERIFY=false

權限錯誤: 確保 Atlassian 賬戶有足夠權限訪問相關空間/項目

調試方法

使用 MCP Inspector 測試:

npx @modelcontextprotocol/inspector uvx mcp-atlassian ...

查看日誌:

# macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# Windows  
type %APPDATA%\Claude\logs\mcp*.log | more

使用 SSE 傳輸

除了標準的 stdio 傳輸，還支持 Server-Sent Events (SSE)：

1. 在終端手動啟動伺服器：

docker run --rm -p 9000:9000 \
  --env-file /path/to/your/.env \
  ghcr.io/sooperset/mcp-atlassian:latest \
  --transport sse --port 9000 -vv

2. 配置 IDE 連接到運行中的伺服器：

{
  "mcpServers": {
    "mcp-atlassian-sse": {
      "url": "http://localhost:9000/sse"
    }
  }
}

安全考慮

• 永遠不要分享 API 令牌
• 保持 .env 文件安全和私密
• 查看 SECURITY.md 了解最佳實踐

技術架構

該項目採用 Docker 容器化部署，通過 Model Context Protocol 與 AI 助手進行通信。支持多種傳輸方式（stdio 和 SSE），能夠靈活適應不同的部署環境和使用場景。

項目設計考慮了企業級應用的需求，支持 Atlassian 的雲版和私有部署版本，提供了完整的認證、權限控制和安全機制。

---

注意: 這不是 Atlassian 官方產品，而是由社區開發者 sooperset 維護的開源項目。