Automox MCP Server

Automox MCP Server

[](https://github.com/AutomoxCommunity/automox-mcp/actions/workflows/ci.yml) [](https://github.com/AutomoxCommunity/automox-mcp/actions/workflows/security.yml) [](https://github.com/AutomoxCommunity/automox-mcp/actions/workflows/release.yml) [](https://badge.fury.io/py/automox-mcp)

The official MCP server for Automox. Talk to your Automox console using natural language — this MCP server connects AI assistants like Claude to your Automox environment so you can manage devices, check compliance, run policies, and more, just by asking.

You:   "Are we ready for Patch Tuesday?"
Claude: Here's your readiness summary — 3 devices need patches,
        2 approvals are pending, and your patch policies run tonight at 2 AM...

> [!IMPORTANT] > Contributions, bug reports, and feature requests are welcome via GitHub Issues and the Automox Community.

> [!CAUTION] > AI assistants can make mistakes. Data produced by the MCP server may be incorrect or incomplete. If you see this happening consistently, please open an issue.

Quick Start

1. Get your Automox credentials

You need three values from the Automox Console:

| Value | Where to find it | |---|---| | API Key | Use an org-scoped key — zone Settings > Secrets & Keys > Add API Key (docs); see key types below | | Account UUID | Settings > Secrets & Keys (shown on the page) | | Org ID | The numeric ID in the URL when viewing your organization |

Automox has two API key types, and the difference matters here:

| | Org-scoped key (recommended) | Global / account key | |---|---|---| | Scope | One organization — the zone it was created in | Every org in the account; inherits the key owner's role per org | | Created at | Zone Settings > Secrets & Keys | Account Global Access Management > Keys (Full Administrator) | | Tool coverage | All tools (verified: works immediately on the search family) | Unreliable on the Advanced Device Search family — advanced_device_search, device_search_typeahead, saved-search create/read/update/delete, list_searches_for_device, get_device_assignments — observed returning 403 in most orgs even for full administrators, while working in others; the upstream authorization behavior is inconsistent and the mechanism is unconfirmed |

> Symptom: 403 on the search tools while reads work everywhere else usually means the key, not your permissions — switch to an org-scoped key for the target org. API Key and Account UUID are always required. Org ID is recommended but optional — some tools that don't require org context will work without it.

2. Create a .env file

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

3. Connect to your AI assistant

Claude Desktop (recommended) — one-click MCPB install:

1. Download the latest automox-mcp-.mcpb from the GitHub Releases page.
2. Open Claude Desktop → Settings → Extensions.
3. Drag the .mcpb file into the Extensions window.
4. Paste your API key, Account UUID, and (optionally) Org ID into the prompts.

No .env file, no terminal — credentials are stored in Claude Desktop's secure config. The bundle pulls the matching automox-mcp release from PyPI on first run.

Claude Code (CLI):

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

Cursor / any other MCP client — add to your MCP config:

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

That's it. Start asking questions.

What Can I Ask?

The server exposes 133 tools across devices, policies, patches, groups, webhooks, worklets, vulnerability sync, maintenance windows, and more. You don't need to know the tool names — just describe what you want:

| Ask this | What happens | |---|---| | "Are we ready for Patch Tuesday?" | Checks pending patches, approvals, and policy schedules | | "What is our compliance posture?" | Returns compliance rates, non-compliant devices, and health breakdown | | "Give me the full profile for the Caldera server" | Combines device details, inventory, packages, and policy status | | "What devices need attention?" | Surfaces devices flagged for immediate action | | "Reboot the device 'Testing box'" | Searches for the device and issues a reboot command | | "Create a patch policy for Firefox targeting the 'MCP testing' group" | Creates the policy with sensible defaults | | "What did Mark Hansen do in Automox last week?" | Queries the audit trail across the date range | | "Find all Windows devices not seen in 30 days" | Uses advanced device search with structured queries | | "Show me vulnerability remediation status" | Lists action sets with issues, solutions, and progress | | "Search the worklet catalog for USB security" | Browses community worklets with evaluation/remediation code |

For the full list of tools, parameters, and MCP resources, see the [Tool Reference](docs/tool-reference.md).

> Tip: You can also ask the server itself — the discover_capabilities tool returns all available tools organized by domain.

Configuration

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | AUTOMOX_API_KEY | Yes | — | Automox API key (org-scoped recommended — see [key types](#1-get-your-automox-credentials)) | | AUTOMOX_ACCOUNT_UUID | Yes | — | Account UUID from Secrets & Keys | | AUTOMOX_ORG_ID | Recommended | — | Numeric organization ID (required by most tools) | | AUTOMOX_MCP_READ_ONLY | No | false | Disable all write operations (85 of 133 tools remain) | | AUTOMOX_MCP_ALLOW_APPLY_REMEDIATION_ACTIONS | No | false | Opt in to the apply_remediation_actions tool, which patches/runs worklets on endpoints immediately. Off by default even in write mode. | | AUTOMOX_MCP_ALLOW_SPLASHTOP_BULK_INSTALL_UNINSTALL | No | false | Opt in to the splashtop_bulk_install_uninstall tool, which installs/uninstalls the Splashtop client across an entire server group in one call. Off by default even in write mode. | | AUTOMOX_MCP_ALLOW_DELETE_DEVICE | No | false | Opt in to the delete_device tool, which permanently deletes a device record and its history (DELETE /servers/{id}). Irreversible and not reconstructable through the MCP. Off by default even in write mode. | | AUTOMOX_MCP_ALLOW_UPLOAD_POLICY_FILE | No | false | Opt in to the upload_policy_file tool, which uploads a local installer file to a Required Software policy. Reads from the local filesystem, so it also requires AUTOMOX_MCP_UPLOAD_ALLOWED_DIRS and only works on the stdio (local) transport. Off by default even in write mode. | | AUTOMOX_MCP_UPLOAD_ALLOWED_DIRS | No | — | Comma-separated absolute directories upload_policy_file may read installers from. Required for that tool to register; paths are canonicalized and must resolve inside an allowed dir. | | AUTOMOX_MCP_UPLOAD_MAX_BYTES | No | 10737418240 | Max installer size for upload_policy_file (default 10 GB, Automox's ceiling). | | AUTOMOX_MCP_UPLOAD_TIMEOUT_SECONDS | No | 3600 | Upload read/write timeout for upload_policy_file (large installers need more than the default request timeout). | | AUTOMOX_MCP_MODULES | No | all | Comma-separated list of modules to load (see below) | | AUTOMOX_MCP_TOKEN_BUDGET | No | 4000 | Max estimated tokens per response before truncation | | AUTOMOX_MCP_SANITIZE_RESPONSES | No | true | Sanitize API data to mitigate prompt injection | | AUTOMOX_MCP_TOOL_PREFIX | No | — | Prefix all tool names (e.g., automox) to prevent cross-server collisions | | AUTOMOX_MCP_LOG_FORMAT | No | text | Log format: text or json (structured JSON for SIEM integration) | | AUTOMOX_MCP_TRANSPORT | No | stdio | Transport: stdio, http, sse, or streamable-http | | AUTOMOX_MCP_HOST | No | 127.0.0.1 | Bind address for HTTP/SSE | | AUTOMOX_MCP_PORT | No | 8000 | Bind port for HTTP/SSE | | AUTOMOX_MCP_API_KEYS | No | — | Comma-separated MCP endpoint API keys for HTTP/SSE Bearer-token auth (e.g., key1,label:key2) | | AUTOMOX_MCP_API_KEY_FILE | No | — | Path to a file containing MCP endpoint API keys (one per line) | | AUTOMOX_MCP_OAUTH_ISSUER | No | — | OIDC issuer URL for JWT auth (e.g., https://auth.example.com/realms/main) | | AUTOMOX_MCP_OAUTH_JWKS_URI | No | — | JWKS endpoint for JWT key rotation (auto-derived from issuer if omitted) | | AUTOMOX_MCP_OAUTH_AUDIENCE | When JWT auth | — | Expected JWT audience claim (prevents token passthrough); required when AUTOMOX_MCP_OAUTH_ISSUER is set | | AUTOMOX_MCP_OAUTH_SERVER_URL | No | — | Canonical server URL; enables RFC 9728 Protected Resource Metadata | | AUTOMOX_MCP_OAUTH_SCOPES | No | — | Comma-separated required OAuth scopes | | AUTOMOX_MCP_ALLOWED_ORIGINS | No | — | Extra allowed Origin headers for DNS rebinding protection (comma-separated) | | AUTOMOX_MCP_ALLOWED_HOSTS | No | — | Extra allowed Host headers for DNS rebinding protection (comma-separated) | | AUTOMOX_MCP_DNS_REBINDING_PROTECTION | No | true | Set to false to disable DNS rebinding protection (not recommended) | | AUTOMOX_MCP_ALLOW_REMOTE_BIND | No | false | Allow binding to non-loopback addresses (required for 0.0.0.0 or external IPs) |

Read-Only Mode

AUTOMOX_MCP_READ_ONLY=true

Disables all write operations. Only read-only tools are registered (85 of 133). Useful for auditing and monitoring.

Modular Loading

Load only the tool modules you need:

AUTOMOX_MCP_MODULES=devices,policies

Available modules: audit, audit_v2, devices, device_search, policies, policy_history, users, groups, events, reports, packages, webhooks, worklets, data_extracts, vuln_sync, compound, policy_windows

Both settings can be combined:

AUTOMOX_MCP_READ_ONLY=true
AUTOMOX_MCP_MODULES=devices,policies

HTTP Transport

For non-stdio deployments:

uvx --env-file .env automox-mcp --transport http --host 127.0.0.1 --port 8000

Endpoint Authentication

When deploying over HTTP or SSE, you can require authentication on the MCP endpoint (separate from the Automox API key). Two strategies are supported:

Static API keys (simple):

automox-mcp --generate-key                         # generate a key
export AUTOMOX_MCP_API_KEYS="amx_mcp_a1b2c3..."    # or use a key file

OAuth 2.1 / JWT (enterprise IdP integration):

export AUTOMOX_MCP_OAUTH_ISSUER="https://auth.example.com/realms/main"
export AUTOMOX_MCP_OAUTH_AUDIENCE="https://mcp.example.com"
export AUTOMOX_MCP_OAUTH_SERVER_URL="https://mcp.example.com"  # enables RFC 9728 metadata

Clients must include Authorization: Bearer on every request. Unauthenticated requests receive 401 Unauthorized with proper WWW-Authenticate headers. No effect on stdio transport.

Security

The Automox MCP server is designed for enterprise deployment with defense-in-depth security controls.

Highlights:

• Read-only mode (AUTOMOX_MCP_READ_ONLY) disables all 48 write tools
• Module filtering (AUTOMOX_MCP_MODULES) for least-privilege tool loading
• Correlation IDs on every tool call, forwarded to Automox API as X-Correlation-ID
• Rate limiting (30 calls/60s) with token budget estimation and auto-truncation
• API key isolation — stored as private attribute with per-request auth injection (no header storage)
• Generic error responses — no internal paths, connection strings, or API keys in error output
• Prompt injection mitigation — API response sanitization with Unicode normalization, homoglyph defense, HTML tag/script stripping, and reference-style markdown stripping
• Webhook secret handling — secrets stripped from idempotency cache after creation
• Structured JSON logging (AUTOMOX_MCP_LOG_FORMAT=json) for SIEM integration
• Tool name prefixing (AUTOMOX_MCP_TOOL_PREFIX) to prevent cross-server collisions
• Sigstore-signed releases with CycloneDX SBOM
• SSRF prevention — webhook URLs validated against private/loopback IPs and cloud metadata endpoints
• MCP endpoint authentication — static API keys or OAuth 2.1/JWT with audience binding and RFC 9728 Protected Resource Metadata
• DNS rebinding protection — Origin and Host header validation on all HTTP/SSE connections per the MCP transport spec
• Security response headers — X-Content-Type-Options, X-Frame-Options, CSP, Cache-Control: no-store, Strict-Transport-Security on all HTTP responses
• Authentication rate limiting — blocks IPs after repeated auth failures to mitigate brute-force attacks
• Remote bind protection — non-loopback HTTP/SSE binding requires explicit --allow-remote-bind opt-in
• MCP Tool Annotations on all 133 tools — readOnlyHint, destructiveHint, idempotentHint, and openWorldHint per the MCP Protocol specification, enabling client-side confirmation dialogs and safety guardrails
• Interactive MCP Apps (io.modelcontextprotocol/ui) — inline review/approval surfaces for consequential flows: compliance triage, patch approval, policy blast-radius, remediation apply, and RBAC access certification. Apps-capable hosts render them inline; other hosts degrade gracefully to the structured tool output. Write-flow Apps drive the existing gated tools through the host's confirmation — no new tools, no new gates — and ship under the host's deny-all CSP (self-contained, no external/CDN loads)
• 61 security hardening items (V-001 through V-182, S-001 through S-006) documented in CHANGELOG and SECURITY.md

Capability model. The server wraps 100% of the published Automox Console API and Webhooks API, with a single deliberate exception — secret-exposing endpoints are never wrapped (API-key decrypt, password-setting). Every destructive operation is either ask-first (host confirmation) or gated behind a default-off env flag. Concretely, three categorical rules:

• Secrets are never handled — the server never returns secret material and never lets the model set it. Credentials enter only via environment/config; decrypt endpoints are not wrapped, password-setting is excluded, and secret fields are redacted from every projection. This is the only intentional omission.
• Destructive operations are two-tier. Single-target, recoverable actions are ask-first (destructiveHint: true, surfaced as a host confirmation dialog, disabled entirely by read-only mode). Operations where per-call confirmation can't protect you — fleet-scale, self-lockout, or arbitrary model-authored code execution — are gated behind explicit, default-off env flags (AUTOMOX_MCP_ALLOW_APPLY_REMEDIATION_ACTIONS, AUTOMOX_MCP_ALLOW_SPLASHTOP_BULK_INSTALL_UNINSTALL, AUTOMOX_MCP_ALLOW_DELETE_DEVICE). Device deletion is gated, not omitted.

The full coverage map, the gating principle, and every intentional omission are documented in [API Coverage & Intentional Omissions](docs/api-coverage.md).

For vulnerability reporting and the full threat model, see [SECURITY.md](SECURITY.md). For deployment hardening (containers, Kubernetes, MCP gateways, TLS, authentication), see the [Deployment Security Guide](docs/deployment-security.md). Security posture is benchmarked against the Wiz MCP Security Best Practices cheat sheet.

> Note: For network-accessible deployments, enable endpoint authentication (static keys via AUTOMOX_MCP_API_KEYS or J

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AutomoxCommunity
• Source: AutomoxCommunity/automox-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.