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:

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

Server/Data Center:

前往個人資料 → 個人訪問令牌
點擊 "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": "[email protected]",
        "CONFLUENCE_API_TOKEN": "your_confluence_api_token",
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "[email protected]", 
        "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)：

在終端手動啟動伺服器：

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

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

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

安全考慮

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

技術架構

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

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

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