Automox MCP

🚀 Automox MCP Server

Automox MCP Server 提供了一個模型上下文協議（MCP）服務器，它能讓 Automox 客戶通過 AI 助手訪問其 Automox 控制檯。該服務器公開了多個高級工作流工具，專注於常見的操作任務，用於管理設備、策略和用戶賬戶。此項目並非完整的 API 包裝器，而是旨在提供一系列針對常見操作場景的 Automox 工作流。

⚠️ 重要提示

本項目正在積極開發中，在穩定的 1.0 版本發佈之前，功能可能會發生變化。歡迎貢獻代碼和提出額外工作流的建議！請通過 GitHub Issues 提供任何反饋。

⚠️ 重要提醒

請記住，AI 遠非完美，它可能會出錯。其生成的數據可能不正確或不完整。如果您發現 MCP 服務器一直存在此類問題，請提交一個 GitHub Issue，以便我們進行調查並在響應中添加更嚴格的防護措施。

🚀 快速開始

可用工具

MCP 服務器公開了 18 個高級工作流工具，用於常見的 Automox 管理任務：

設備管理（6 個工具）

• list_devices：彙總整個組織的設備清單和策略狀態。默認情況下包括未管理的設備，並支持 policy_status/managed 過濾器，因此您可以專注於例如不符合要求的受管端點。
• device_detail：返回精心整理的設備上下文（最近的策略狀態、分配情況、排隊的命令、關鍵信息）。僅當您明確需要 Automox 原始有效負載的清理切片時，才傳遞 include_raw_details=true。
• devices_needing_attention：顯示需要立即處理的 Automox 設備。
• search_devices：按主機名、IP、標籤、狀態或缺失補丁的嚴重程度搜索 Automox 設備。
• device_health_metrics：彙總組織的設備健康指標。提供 limit 以採樣較少的設備（默認 500 個），並提供 max_stale_devices 以限制陳舊設備列表，以便獲得適合令牌的響應。
• execute_device_command：向設備發出即時命令（掃描、全部打補丁、特定打補丁、重啟）。

策略管理（9 個工具）

• policy_health_overview：總結最近的 Automox 策略活動。如果省略 org_uuid，服務器將從 AUTOMOX_ORG_ID / AUTOMOX_ORG_UUID 解析它。
• policy_execution_timeline：查看策略的最近執行情況。
• policy_run_results：獲取特定執行令牌（由 policy_execution_timeline 返回）的每個設備的結果（標準輸出、標準錯誤、退出代碼）。
• policy_catalog：列出 Automox 策略及其類型和狀態摘要。支持 page（從 0 開始索引）和 limit 分頁；檢查 metadata.pagination.has_more，閱讀 metadata.notes，並根據需要遵循可選的 metadata.suggested_next_call 提示以繼續獲取額外的切片。
• policy_detail：檢索策略的配置和最近歷史記錄。
• apply_policy_changes：預覽或提交結構化的策略創建/更新操作。自動將輔助字段（filter_name、filter_names）和友好的調度塊規範化為 Automox 預期的有效負載，確保在提交之前包含所需字段（例如 schedule_days、schedule_time）。
• patch_approvals_summary：總結待處理的補丁批准及其嚴重程度。
• decide_patch_approval：批准或拒絕 Automox 補丁批准請求。
• execute_policy_now：立即執行策略以進行補救（所有設備或特定設備）。

賬戶管理（2 個工具）

• invite_user_to_account：邀請用戶加入 Automox 賬戶，並可選擇分配區域。
• remove_user_from_account：按 UUID 從 Automox 賬戶中移除用戶。

審計跟蹤（1 個工具）

• audit_trail_user_activity：檢索特定用戶在給定日期執行的 Automox 審計跟蹤事件，並支持可選的分頁遊標。如果需要更深入的調查，請設置 include_raw_events=true 以包含清理後的事件有效負載。傳遞完整的電子郵件地址或提供 actor_name/部分電子郵件提示，工具將自動解析匹配的 Automox 用戶。

示例工作流

以下是一些如何結合 AI 助手使用 MCP 服務器的實際示例：

設備健康摘要

快速瞭解設備健康狀況：

詢問：“關於我在 Automox 中的設備健康狀況，你能告訴我什麼？”

MCP 服務器將返回全面的摘要，包括：

• 整體設備群健康狀況（設備總數、合規率）
• 設備狀態細分（就緒、未就緒、需要重啟、正在刷新）
• 打補丁狀態（有待處理補丁的設備、需要關注的設備）
• 檢查最近情況分析（最近 24 小時、7 天、30 天、30 天以上）
• 關鍵觀察結果和建議的下一步操作

重啟設備

簡單而有效的設備管理：

詢問：“你能重啟 Automox 中的 'Testing box' 設備嗎？”

AI 助手將：

1. 搜索匹配主機名的設備
2. 如果有多個匹配設備，則展示出來
3. 確認後執行重啟命令
4. 甚至可以通過檢查設備正常運行時間來驗證重啟是否成功

創建和更新策略

創建一個補丁策略，使 Firefox 保持最新：

詢問：“你能創建一個使 Firefox 保持最新的補丁策略嗎？
確保在補丁策略名稱中包含 'henry'，並針對 'MCP testing' 組中的設備。”

MCP 服務器將：

1. 按名稱查找服務器組
2. 創建啟用自動打補丁的補丁策略
3. 配置調度（默認工作日凌晨 2 點）
4. 設置用戶通知
5. 顯示創建的策略配置

您還可以輕鬆更新策略調度：

詢問：“你能將 'Auto - Patch Firefox - henry' 策略更新為僅在工作日運行嗎？”

AI 將自動將調度從週末更新為工作日。

檢查審計日誌

查看 Automox 控制檯中的用戶活動：

詢問：“Mark Hansen 上週在我們的 Automox 控制檯中做了什麼？”

MCP 服務器將：

1. 查詢指定日期範圍內每天的審計跟蹤
2. 按天總結所有活動
3. 提供總數並突出顯示關鍵操作（策略更改、設備操作、用戶管理）
4. 識別諸如策略清理或重組活動等模式

生成報告

MCP 服務器支持生成全面的報告（由於具有 PDF 生成功能，與 Claude Desktop 配合使用效果最佳）：

詢問：“生成一份關於我們的策略健康狀況和設備狀態的全面報告”

AI 可以：

• 從多個端點收集數據
• 編譯統計信息和趨勢
• 將信息格式化為可讀的報告
• 導出為 PDF 格式（使用 Claude Desktop 時）

💡 使用建議

報告生成可能需要幾分鐘時間，具體取決於組織規模。使用像 Haiku 這樣較輕量級的模型可以加快速度，但可能會在細節上有所取捨。該過程可根據您的需求進行高度定製。

工具參數

大多數工具接受可選參數，用於過濾和分頁：

• 設備工具：group_id、limit、include_unmanaged、device_id
• 策略工具：org_uuid（可選；從配置的 Automox 組織自動解析）、window_days、report_days、policy_id
• 搜索工具：hostname_contains、ip_address、tag、patch_status
• 審計工具：date、actor_email、actor_uuid、cursor、limit、include_raw_events、org_uuid（可選）
• 執行工具：
  • execute_policy_now：policy_id（必需）、action（remediateAll 或 remediateDevice）、device_id（可選，remediateDevice 時必需）
  • execute_device_command：device_id（必需）、command_type（scan、patch_all、patch_specific、reboot）、patch_names（可選，patch_specific 時必需）
  • apply_policy_changes：接受一個或多個 operations，每個條目包含 action（create/update）和一個策略有效負載。該輔助工具接受方便的簡寫（filter_name、filter_names），轉換友好的 schedule 塊，並強制執行 Automox 友好的默認值（例如，更新時包含 id）。
  • policy_run_results：policy_uuid、exec_token 和可選過濾器（org_uuid、result_status、device_name、分頁參數）。

設置與使用

前提條件

• Python 3.11 或更高版本
• uv（推薦）或 pip
• Automox 賬戶信息
  • 賬戶 UUID
  • 組織 ID
  • API 憑證

在控制檯中查找值

• API 密鑰：登錄 Automox 控制檯 → 省略號（右上角）→ 秘密與密鑰 → 添加 API 密鑰 (文檔)
• 賬戶 UUID：也可在秘密與密鑰部分找到。
• 組織 ID：您組織的 6 位數字標識符 - 通常可以在 Automox 控制檯中管理組織時的 URL 中找到。

環境配置

創建一個包含 API 憑證的 .env 文件：

cp .env.example .env

然後編輯 .env 文件以添加您的憑證：

AUTOMOX_API_KEY=your-api-key
AUTOMOX_ACCOUNT_UUID=your-account-uuid-here
AUTOMOX_ORG_ID=your-org-id-here

快速開始（無需安裝）

運行 Automox MCP 服務器最簡單的方法是使用 uvx，它會自動下載並運行該包：

uvx --env-file .env automox-mcp

這種方法：

• 無需安裝步驟
• 自動使用最新版本
• 從 .env 文件加載環境變量
• 用於 MCP 客戶端配置（見下面的編輯器/助手集成）

通過 HTTP 或 SSE 運行

CLI 入口點現在支持所有 FastMCP 傳輸。傳遞 --transport http 以啟用現代可流式 HTTP 傳輸，或傳遞 --transport sse 以使用服務器發送事件。

# 可流式 HTTP（推薦）
uvx --env-file .env automox-mcp --transport http --host 127.0.0.1 --port 8000

# 舊版 SSE 傳輸（僅當您的客戶端需要 SSE 時使用）
uvx --env-file .env automox-mcp --transport sse --host 127.0.0.1 --port 8000

如果省略 --host/--port，CLI 默認使用 127.0.0.1:8000。對於無頭部署，可以使用環境變量（AUTOMOX_MCP_TRANSPORT、AUTOMOX_MCP_HOST、AUTOMOX_MCP_PORT、AUTOMOX_MCP_PATH）提供相同的值。

替代方案：持久安裝

如果您更喜歡持久安裝，可以全局安裝該包：

使用 uv

uv tool install automox-mcp

使用 pip

pip install automox-mcp

然後在 shell 中設置環境變量後運行：

export AUTOMOX_API_KEY="your-api-key"
export AUTOMOX_ACCOUNT_UUID="your-account-uuid"
export AUTOMOX_ORG_ID="your-org-id"
automox-mcp

編輯器/助手集成

您可以將 Automox MCP 服務器與編輯器或 AI 助手集成。以下是流行 MCP 客戶端的配置示例：

如果您安裝了 Claude CLI

claude mcp add automox-mcp uvx -- --env-file /path/to/.env automox-mcp

使用 uvx（推薦）

{
  "mcpServers": {
    "automox-mcp": {
      "command": "uvx",
      "args": [
        "--env-file",
        "/path/to/.env",
        "automox-mcp"
      ]
    }
  }
}

使用單獨的環境變量

{
  "mcpServers": {
    "automox-mcp": {
      "command": "uvx",
      "args": ["automox-mcp"],
      "env": {
        "AUTOMOX_API_KEY": "your-api-key",
        "AUTOMOX_ACCOUNT_UUID": "your-account-uuid-here",
        "AUTOMOX_ORG_ID": "your-org-id-here"
      }
    }
  }
}

貢獻代碼

開始貢獻

克隆倉庫：

git clone https://github.com/AutomoxCommunity/automox-mcp.git
cd automox-mcp

以開發模式安裝（倉庫通過 .python-version 指定 Python 3.13）：

# 確保指定的解釋器可用
uv python install

# 創建 .venv 並安裝項目和開發依賴項
uv sync --python 3.13 --dev

測試

我們建議使用 MCP Inspector 進行交互式調試。我們包含了一個 fastmcp.json 配置，方便啟動。

fastmcp dev

這將在 http://localhost:6274 打開，您可以在其中交互式地測試工具。

如果您想在本地使用 Claude Code 進行測試：

claude mcp add automox-mcp uvx -- --from . --env-file .env automox-mcp

運行測試

uv run --python 3.13 --dev pytest

MCP 掃描器

我們使用 Cisco 的 MCP 掃描器 對 MCP 服務器實現進行靜態分析。

mcp-scanner \
  --stdio-command uv \
  --stdio-args run automox-mcp \
  --stdio-env AUTOMOX_API_KEY=test-api-key \
  --stdio-env AUTOMOX_ACCOUNT_UUID=test-account \
  --stdio-env AUTOMOX_ORG_ID=0 \
  --stdio-env AUTOMOX_MCP_SKIP_DOTENV=1 \
  --analyzers yara \
  --format summary

版本控制

本項目遵循 語義化版本控制。

準備發佈時：

1. 在 pyproject.toml 中更新新版本號。
2. 提交更改並創建匹配的 Git 標籤（例如，v0.1.0）。
3. 當您推送標籤時，發佈工作流將自動構建併發布到 PyPI。

許可證

本項目採用 MIT 許可證。有關詳細信息，請參閱 LICENSE 文件。

支持

這是一個社區驅動的項目，雖然得到積極維護，但 Automox 不提供官方支持。

如需請求幫助，請提交一個 GitHub Issue。這是提出問題、報告錯誤、請求功能、提出增強建議和更新文檔的合適渠道。