automox-mcp

# Automox MCP Server

<!-- mcp-name: com.automox/automox-mcp -->

[![CI](https://github.com/AutomoxCommunity/automox-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/AutomoxCommunity/automox-mcp/actions/workflows/ci.yml)
[![Security Scans](https://github.com/AutomoxCommunity/automox-mcp/actions/workflows/security.yml/badge.svg)](https://github.com/AutomoxCommunity/automox-mcp/actions/workflows/security.yml)
[![Publish Release](https://github.com/AutomoxCommunity/automox-mcp/actions/workflows/release.yml/badge.svg)](https://github.com/AutomoxCommunity/automox-mcp/actions/workflows/release.yml)
[![PyPI version](https://badge.fury.io/py/automox-mcp.svg)](https://badge.fury.io/py/automox-mcp)

The official MCP server for Automox. Talk to your Automox console using natural language — this [MCP server](https://modelcontextprotocol.io/) 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]
> This repository does not accept external contributions. For bug reports or feature requests, use [help.automox.com](https://help.automox.com).

> [!CAUTION]
> AI assistants can make mistakes. Data produced by the MCP server may be incorrect or incomplete. If you see this happening consistently, please let us know via [help.automox.com](https://help.automox.com).

## Quick Start

### 1. Get your Automox credentials

You need three values from the [Automox Console](https://console.automox.com):

| Value | Where to find it |
|---|---|
| **API Key** | Use an **org-scoped** key — zone **Settings > Secrets & Keys > Add API Key** ([docs](https://docs.automox.com/product/Product_Documentation/Settings/Managing_Keys.htm)); 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

```bash
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-<version>.mcpb` from the [GitHub Releases page](https://github.com/AutomoxCommunity/automox-mcp/releases/latest).
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):**
```bash
claude mcp add automox-mcp uvx -- --env-file /path/to/.env automox-mcp
```

**Cursor / any other MCP client** — add to your MCP config:
```json
{
  "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_RE