JinDaGe - automox-mcp MCP Details

article

README

🚀 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 助手将：

搜索匹配主机名的设备
如果有多个匹配设备，则展示出来
确认后执行重启命令
甚至可以通过检查设备正常运行时间来验证重启是否成功

创建和更新策略

创建一个补丁策略，使 Firefox 保持最新：

询问：“你能创建一个使 Firefox 保持最新的补丁策略吗？
确保在补丁策略名称中包含 'henry'，并针对 'MCP testing' 组中的设备。”

MCP 服务器将：

按名称查找服务器组
创建启用自动打补丁的补丁策略
配置调度（默认工作日凌晨 2 点）
设置用户通知
显示创建的策略配置

您还可以轻松更新策略调度：

询问：“你能将 'Auto - Patch Firefox - henry' 策略更新为仅在工作日运行吗？”

AI 将自动将调度从周末更新为工作日。

检查审计日志

查看 Automox 控制台中的用户活动：

询问：“Mark Hansen 上周在我们的 Automox 控制台中做了什么？”

MCP 服务器将：

查询指定日期范围内每天的审计跟踪
按天总结所有活动
提供总数并突出显示关键操作（策略更改、设备操作、用户管理）
识别诸如策略清理或重组活动等模式

生成报告

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

版本控制

本项目遵循语义化版本控制。

准备发布时：

在 pyproject.toml 中更新新版本号。
提交更改并创建匹配的 Git 标签（例如，v0.1.0）。
当您推送标签时，发布工作流将自动构建并发布到 PyPI。

许可证

本项目采用 MIT 许可证。有关详细信息，请参阅 LICENSE 文件。

支持

这是一个社区驱动的项目，虽然得到积极维护，但 Automox 不提供官方支持。

如需请求帮助，请提交一个 GitHub Issue。这是提出问题、报告错误、请求功能、提出增强建议和更新文档的合适渠道。