Skip to content

AutomoxCommunity/automox-mcp

BranchesTags

Repository files navigation

Automox MCP Server

CI Security Scans Publish Release PyPI version

This project provides a Model Context Protocol (MCP) server that enables Automox customers to access their Automox console through AI assistants. The server exposes several high-level workflow tools for managing devices, policies, and user accounts with a focus on common operational tasks.

Rather than a full API wrapper, this package aims to offer a curated set of Automox workflows tailored to common operational scenarios.

Important

The project is under active development. Functionality may change before a stable 1.0 release. Contributions and suggestions for additional workflows are welcome! Please provide any feedback through GitHub Issues.

Caution

Please keep in mind that AI is still nowhere near perfect and it can make mistakes. The data it produces can be incorrect or incomplete. If you see this happening consistently with the MCP server, please open a GitHub Issue so we can investigate and add stronger guardrails around responses.

Table of Contents

Available Tools

The MCP server exposes 18 high-level workflow tools designed for common Automox management tasks:

Device Management (6 tools)

  • list_devices - Summarize device inventory and policy status across the organization. Includes unmanaged devices by default and supports policy_status/managed filters so you can zero in on, for example, non-compliant managed endpoints.
  • device_detail - Return curated device context (recent policy status, assignments, queued commands, key facts). Pass include_raw_details=true only when you explicitly need a sanitized slice of the raw Automox payload.
  • devices_needing_attention - Surface Automox devices flagged for immediate action.
  • search_devices - Search Automox devices by hostname, IP, tag, status, or severity of missing patches.
  • device_health_metrics - Aggregate device health metrics for the organization. Supply limit to sample fewer devices (default 500) and max_stale_devices to cap the stale-device list for token-friendly responses.
  • execute_device_command - Issue an immediate command to a device (scan, patch_all, patch_specific, reboot).

Policy Management (9 tools)

  • policy_health_overview - Summarize recent Automox policy activity. Omit org_uuid to let the server resolve it from AUTOMOX_ORG_ID / AUTOMOX_ORG_UUID.
  • policy_execution_timeline - Review recent executions for a policy.
  • policy_run_results - Fetch per-device results (stdout, stderr, exit codes) for a specific execution token returned by policy_execution_timeline.
  • policy_catalog - List Automox policies with type and status summaries. Supports page (0-indexed) and limit pagination; inspect metadata.pagination.has_more, read metadata.notes, and follow the optional metadata.suggested_next_call hint to keep fetching additional slices when needed.
  • policy_detail - Retrieve configuration and recent history for a policy.
  • apply_policy_changes - Preview or submit structured policy create/update operations. Automatically normalizes helper fields (filter_name, filter_names) and friendly schedule blocks into Automox’s expected payloads, ensuring required fields (e.g., schedule_days, schedule_time) are present before submission.
  • patch_approvals_summary - Summarize pending patch approvals and their severity.
  • decide_patch_approval - Approve or reject an Automox patch approval request.
  • execute_policy_now - Execute a policy immediately for remediation (all devices or specific device).

Account Management (2 tools)

  • invite_user_to_account - Invite a user to the Automox account with optional zone assignments.
  • remove_user_from_account - Remove a user from the Automox account by UUID.

Audit Trail (1 tool)

  • audit_trail_user_activity - Retrieve Automox audit trail events performed by a specific user on a given date, with optional pagination cursor support. Set include_raw_events=true to include sanitized event payloads when deeper investigation is required. Pass either the full email address or provide actor_name/partial email hints and the tool will resolve the matching Automox user automatically.

Example Workflows

Below are some real-world examples of how you can utilize the MCP server with your AI assistant.

Device Health Summary

Get a quick snapshot of your device health:

Ask: "What can you tell me about the health of my devices in Automox?"

The MCP server will return a comprehensive summary including:

  • Overall fleet health (total devices, compliance rate)
  • Device status breakdown (ready, not ready, needs reboot, refreshing)
  • Patching status (devices with pending patches, devices needing attention)
  • Check-in recency analysis (last 24 hours, 7 days, 30 days, 30+ days)
  • Key observations and suggested next steps

Reboot a Device

Simple yet effective device management:

Ask: "Can you reboot the device 'Testing box' in Automox?"

The AI assistant will:

  1. Search for devices matching the hostname
  2. Present matching devices if there are multiple
  3. Execute the reboot command once confirmed
  4. Can even verify the reboot was successful by checking device uptime

Create and Update Policies

Create a patch policy to keep Firefox up to date:

Ask: "Can you create a patch policy that keeps Firefox up to date?
     Make sure to include 'henry' somewhere in the name of the patch policy
     and target the devices in the 'MCP testing' group."

The MCP server will:

  1. Look up the server group by name
  2. Create a patch policy with auto-patching enabled
  3. Configure the schedule (weekdays at 2 AM by default)
  4. Set up user notifications
  5. Display the created policy configuration

You can also easily update policy schedules:

Ask: "Can you update the 'Auto-Patch Firefox - henry' policy to only run on weekdays?"

The AI will update the schedule from weekend to weekdays automatically.

Check the Audit Log

Review user activity in your Automox console:

Ask: "What did Mark Hansen do in our Automox console last week?"

The MCP server will:

  1. Query the audit trail for each day in the specified date range
  2. Summarize all activities by day
  3. Provide totals and highlight key actions (policy changes, device operations, user management)
  4. Identify patterns like policy cleanup or reorganization activities

Report Generation

The MCP server supports generating comprehensive reports (works best with Claude Desktop due to PDF generation capabilities):

Ask: "Generate a comprehensive report on our policy health and device status"

The AI can:

  • Gather data from multiple endpoints
  • Compile statistics and trends
  • Format the information into a readable report
  • Export to PDF format (when using Claude Desktop)

Note

Report generation may take several minutes depending on organization size. Using a lighter model like Haiku can speed this up, though with potential trade-offs in detail. The process is highly customizable based on your needs.

Tool Parameters

Most tools accept optional parameters for filtering and pagination:

  • Device tools: group_id, limit, include_unmanaged, device_id
  • Policy tools: org_uuid (optional; auto-resolved from configured Automox org), window_days, report_days, policy_id
  • Search tools: hostname_contains, ip_address, tag, patch_status
  • Audit tools: date, actor_email, actor_uuid, cursor, limit, include_raw_events, org_uuid (optional)
  • Execution tools:
    • execute_policy_now: policy_id (required), action (remediateAll or remediateDevice), device_id (optional, required for remediateDevice)
    • execute_device_command: device_id (required), command_type (scan, patch_all, patch_specific, reboot), patch_names (optional, required for patch_specific)
    • apply_policy_changes: accepts one or more operations where each entry contains action (create/update) and a policy payload. The helper accepts convenient shorthands (filter_name, filter_names), converts friendly schedule blocks, and enforces Automox-friendly defaults (e.g., inclusion of id during updates).
    • policy_run_results: policy_uuid, exec_token, and optional filters (org_uuid, result_status, device_name, pagination arguments).

Setup & Usage

Prerequisites

  • Python 3.11 or newer
  • uv (recommended) or pip
  • Automox Account info
    • Account UUID
    • Org ID
    • API credentials

Finding the values in your console

  • API Key: Log in to Automox Console → Ellipsis (Top Right) → Secrets & Keys → Add API Key (Docs)
  • Account UUID: Also found in Secrets & Keys section.
  • Org ID: Your organization's 6 digit numeric identifier - you can usually find this in the URL when managing your organization in the Automox Console.

Environment Configuration

Create a .env file with your API credentials:

cp .env.example .env

Then edit .env to add your credentials:

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

Quick Start (No Installation Required)

The easiest way to run the Automox MCP server is using uvx, which automatically downloads and runs the package:

uvx --env-file .env automox-mcp

This approach:

  • Requires no installation step
  • Automatically uses the latest version
  • Loads environment variables from your .env file
  • Used in MCP client configurations (see Editor/Assistant Integrations below)

Run Over HTTP or SSE

The CLI entry point now supports all FastMCP transports. Pass --transport http to enable the modern streamable HTTP transport or --transport sse for Server-Sent Events.

# Streamable HTTP (recommended)
uvx --env-file .env automox-mcp --transport http --host 127.0.0.1 --port 8000

# Legacy SSE transport (only when your client requires SSE)
uvx --env-file .env automox-mcp --transport sse --host 127.0.0.1 --port 8000

If you omit --host/--port, the CLI defaults to 127.0.0.1:8000. The same values can be provided with environment variables (AUTOMOX_MCP_TRANSPORT, AUTOMOX_MCP_HOST, AUTOMOX_MCP_PORT, AUTOMOX_MCP_PATH) for headless deployments.

Alternative: Persistent Installation

If you prefer a persistent installation, you can install the package globally:

Using uv

uv tool install automox-mcp

Using pip

pip install automox-mcp

Then run with environment variables set in your shell:

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

Editor/Assistant Integrations

You can integrate the Automox MCP server with your editor or AI assistant. Here are configuration examples for popular MCP clients:

If you have Claude CLI installed

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

Using uvx (recommended)

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

With Individual Environment Variables

{
  "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"
      }
    }
  }
}

Contributing

Getting started

Clone the repository:

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

Install in development mode (the repo pins Python 3.13 via .python-version):

# Ensure the pinned interpreter is available
uv python install

# Create .venv and install project + dev dependencies
uv sync --python 3.13 --dev

Testing

We recommend using the MCP Inspector for interactive debugging. We include a fastmcp.json configuration for easy startup.

fastmcp dev

This should open at http://localhost:6274 where you can test tools interactively.

If you want to test locally with something like Claude Code:

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

Running tests

uv run --python 3.13 --dev pytest

MCP Scanner

We use Cisco's MCP Scanner for static analysis of the MCP server implementation.

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

Versioning

The project follows Semantic Versioning.

When preparing a release:

  1. Update pyproject.toml with the new version number.
  2. Commit the changes and create a matching Git tag (for example, v0.1.0).
  3. The release workflow will automatically build and publish to PyPI when you push the tag.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Support

This is a community-driven project, actively maintained but not officially supported by Automox.

To request assistance, please open a GitHub Issue. This is the appropriate channel for questions, bug reports, feature requests, enhancement suggestions, and documentation updates.

About

An MCP server implementation for Automox

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v0.1.0 - Initial Release Latest
Nov 13, 2025

Packages

No packages published

Languages