Action1 RMM (unofficial)

action1-mcp-server

An unofficial Model Context Protocol (MCP) server for the Action1 RMM REST API. It lets Claude (or any other MCP host) query your Action1 fleet, run PowerShell on Windows and Bash on macOS, deploy updates, reboot endpoints, search audit trails and build CVE remediation plans, with a guard that keeps state changes off unless you switch them on.

Unofficial project. This server is not affiliated with, endorsed by, sponsored by or supported by Action1 Corporation. "Action1" is a trademark of Action1 Corporation. See NOTICE.

Status

Every operation of the pinned Action1 OpenAPI snapshot is reachable through a tool (see What is covered). The server speaks stdio and Streamable HTTP and ships as an MCPB bundle for Claude Desktop. Releases and their changes: CHANGELOG.md.

Validation status

Read this before you let an agent change anything in your fleet.

• Automated tests (npm test) run against mocked Action1 responses: unit tests, MCP protocol round trips through the SDK client, the destructive-guard truth table, redaction and size limits. Every generated tool that changes state is driven through MCP to prove it is guarded. These tests run in CI on Node 22, 24 and 26.
• Live runs against a real Action1 tenant are recorded in TESTING.md. They were made while versions 0.1 to 0.3 were developed and were not dated. They cover the read tools (organizations, endpoints, pagination, templates, missing updates), read-only script execution on Windows and macOS (action1_execute_and_wait, action1_run_script) and the guard's refusal paths.
• Read-only live shape check (2026-10-26) for 0.6.0: GET requests against a real tenant compared the returned record shapes with the vendored spec. Endpoints, vulnerabilities, installed software, automation instances and schedules, missing updates, endpoint groups and both list envelopes match the spec; audit events are still unverified (the key lacked view_audit). Details in TESTING.md. Apart from this check, the changes in 0.6.0 are covered by the automated tests only; a live smoke run of the 0.6.0 tools is pending.
• Never run against a live tenant: action1_reboot_endpoint, action1_deploy_update, action1_deploy_package, action1_uninstall_program, action1_run_data_collection, removing an endpoint from a group, action1_run_script with target_type: "EndpointGroup", every generated tool that changes state, and every account operation (users, roles, organizations, enterprise). Their request bodies follow the Action1 OpenAPI spec and are checked by tests, but nobody has confirmed that Action1 accepts them. Try them on a test endpoint first and look at the dry-run preview before you execute.

Maintenance status

• Maintained on a best-effort basis by one maintainer (@mguttmann) in spare time. The author uses it in production. There is no support contract and no guaranteed response time.
• Security fixes take priority over features. Report vulnerabilities privately (see Security).
• Dependency updates come from Dependabot; CI fails when a runtime dependency has a known high or critical advisory. A weekly job reports when Action1 serves a different API spec than the pinned snapshot.
• Only the latest minor release gets fixes.
• Issues and pull requests are welcome; see docs/CONTRIBUTING.md and the Code of Conduct.

Why this project

Action1 has a clean REST API, but a few quirks silently produce wrong results when an LLM calls it naively:

• macOS Bash actions need a ten-field run_script payload; the API answers not applicable to Mac platform for any missing field.
• Windows PowerShell actions need a non-empty success_exit_codes.
• last_seen is YYYY-MM-DD_HH-MM-SS (UTC), not ISO-8601, so Date.parse returns NaN. The server parses it and renders it readable.
• The self URL of a list item contains a /general segment that is not a real REST resource.
• Script output is interleaved with Starting / Waiting / Completed lifecycle markers that need to be filtered.
• OS is upper-case and platform lower-case, and both can carry the platform string; one detector normalises them.

The curated tools encode all of these. What the server does not cover is listed in docs/api-coverage-gaps.md.

Install

Claude Desktop: MCPB bundle (recommended)

1. Download action1-mcp-<version>.mcpb from the project's GitHub Releases. The release workflow attaches it to every version tag.
2. Double-click it (or drag it onto Claude Desktop, or use Settings > Extensions > Install from file).
3. Fill in the wizard: API base URL of your region, organization ID, client ID and client secret, and whether destructive operations are allowed (leave this off at first).

Claude Desktop runs the bundle with its built-in Node.js. Details and troubleshooting: docs/INSTALLATION.md.

MCP Registry

The release workflow lists the bundle of each stable release in the official MCP Registry as io.github.mguttmann/action1-mcp (download URL and SHA-256 of the release asset, the environment variables of the bundle). MCP hosts and directories that read the registry can install it from there. Only that name is this project; Action1 servers under other namespaces are different code.

glama.json names the maintainer of the Glama listing.

From source (any MCP host)

Requires Node.js 22.12 or newer (engines in package.json); CI tests Node 22, 24 and 26.

git clone https://github.com/mguttmann/action1-mcp.git
cd action1-mcp
npm ci
cp .env.example .env             # fill in your Action1 credentials
npm run build                    # compiles to dist/ (tsc only)

Attach it to Claude Code:

claude mcp add action1 -- node --env-file=$(pwd)/.env $(pwd)/dist/index.js

npm run inspector opens the MCP Inspector against the built server (needs Node 22.19 or newer). Other hosts (Claude Desktop with a JSON config, Claude.ai, Cursor, Continue.dev, Cody) are covered in docs/INSTALLATION.md.

npm

Publishing to npm is planned but has not happened yet. There is no official npm package, so do not install action1-mcp-server or any similarly named package from the registry: it would not be this code.

What is covered

• Generated tools: every operation of the pinned Action1 OpenAPI snapshot (date in src/codegen/spec/SOURCE.md) becomes a verb-first tool such as action1_list_endpoint_groups, unless a curated tool covers it. Exceptions: POST /oauth2/token is used internally and not exposed, and the two package-upload operations return an explanatory error because they need a binary body. The full mapping is generated into docs/_coverage_table.md; docs/api-coverage.md explains it.
• Curated tools for the common workflows, including high-level wrappers (CVE remediation plan, audit log search, software inventory, recurring schedules, report export, group resolver).
• Resources (action1://me, action1://orgs, action1://templates, action1://reports, action1://endpoints/{orgId}, action1://groups/{orgId}, action1://vulnerabilities/{orgId}) for hosts that pre-fetch context.
• Slash prompts for multi-step jobs (/patch-windows-fleet, /audit-vulnerabilities, /triage-offline-endpoints, /run-script-fleetwide, /software-inventory-sweep, /check-my-permissions).

tests/unit/specSha.test.ts ties the generated tools to the pinned snapshot. It does not see changes at Action1; npm run spec:check and a weekly CI job compare the snapshot with the spec Action1 serves.

Highlights

• Guarded state changes. Tools that change state need ACTION1_ALLOW_DESTRUCTIVE=true, default to a dry-run preview and need confirm: "YES" to execute. Account operations need a second switch. See Destructive guard.
• Scoping. ACTION1_ALLOWED_ORG_IDS limits which organizations the tools may address; ACTION1_TOOLSETS=read registers only read-only tools.
• Output for agents. Every read-only tool accepts response_format (markdown default, json); every tool sets all four MCP annotations and declares an outputSchema. Paginated results carry count, has_more, next_cursor, and total on the final page. Results stay under the 1 MB host limit with visible truncation notes.
• Strict inputs. Unknown or misspelled arguments are rejected with a validation error instead of being ignored.
• Auth. OAuth2 client credentials with proactive refresh, deduplicated concurrent token requests and a refresh-token fallback.
• Transport safety. Reads (GET/HEAD) are retried on network errors, HTTP 5xx and 429 (honouring Retry-After). Mutations are sent once and retried only on 429 or when the connection failed before the request was sent, so a retry never runs an action twice. Every Action1 call is bounded by ACTION1_REQUEST_TIMEOUT_MS.
• Two transports. stdio (default) and stateless Streamable HTTP, both serving MCP 2026-07-28 next to the 2025 revisions (ADR 0001). HTTP requires a bearer token, checks Host and Origin against DNS rebinding, limits bodies to 1 MB and rate-limits per client IP.
• Logs. Structured JSON lines on stderr with credential redaction, one tool_call line per call and audit lines for guarded operations. Stdout is reserved for MCP.

Architecture

+----------------------------------------------------------------------+
| Curated tools and workflow wrappers                                  |
|  - script execution (Windows, macOS, OS-aware routing)               |
|  - execute_and_wait (start + poll + filtered output)                 |
|  - get_endpoint (canonical path + list fallback)                     |
|  - CVE remediation plan, audit log search, software inventory, ...   |
+----------------------------------------------------------------------+
| Generated tools                                                      |
|  - one tool per remaining spec operation, verb-first snake_case      |
|  - shared runtime: pagination, destructive guard, error mapping      |
|  - Action1 OpenAPI 3.1 snapshot, SHA-pinned (spec/openapi.sha256)    |
+----------------------------------------------------------------------+
| Shared infrastructure                                                |
|  - Action1Client (auth, retry, timeouts, path safety, error mapping) |
|  - TokenProvider (refresh_token fallback, proactive refresh)         |
|  - destructive guard, org allowlist, toolset filter                  |
|  - structured stderr logger with redaction                           |
|  - Markdown table renderer, response size budgets                    |
+----------------------------------------------------------------------+

When a generated tool would get the same name as a curated tool, the code generator (src/codegen/generate.ts) drops the generated one; operations listed in SKIP_OPERATION_IDS (src/codegen/curated-overrides.ts) are skipped as well. Design decisions are recorded in docs/adr/.

Configuration

All configuration is via environment variables. Copy .env.example to .env and fill it in; empty values mean "use the default". node dist/index.js --help lists the same variables.

Action1 regions (ACTION1_BASE_URL):

Connecting to MCP hosts

Tools

docs/USAGE.md is the tool reference and docs/EXAMPLES.md has end-to-end recipes. The curated layer in short:

Discovery (read-only)

action1_list_organizations, action1_list_endpoints, action1_endpoints_summary (server-side counters, small output regardless of fleet size), action1_get_endpoint (canonical path with list fallback, plus derived platform and connectivity.online), action1_search_endpoints (substring filter on hostname, user, OS, status), action1_list_action_templates, action1_get_action_template, action1_list_missing_updates, action1_list_vulnerabilities, action1_list_recent_automations, action1_automations_summary.

Execution (destructive, guarded)

action1_run_powershell (Windows; fills success_exit_codes), action1_run_bash_macos (macOS; fills the ten run_script fields), action1_run_script (routes by OS), action1_reboot_endpoint, action1_deploy_update, action1_deploy_package, action1_uninstall_program, action1_run_data_collection. All accept target_type: "Endpoint" (default) or "EndpointGroup"; action1_run_script then also needs os ("windows" or "macos"), because a group has no single OS to detect.

Polling and results (read-only)

action1_get_automation_status, action1_get_automation_results, action1_get_automation_output (filters lifecycle markers), action1_wait_for_automation.

Workflows (destructive, guarded)

action1_execute_and_wait: start an action, poll until it ends and return the filtered output. Routes by OS in mode: "script" or runs a named template in mode: "template".

High-level wrappers

action1_endpoint_groups_resolve (fuzzy group name to UUID), action1_software_inventory_for_endpoint, action1_recurring_schedules, action1_audit_log_search, action1_report_export, action1_cve_remediation_plan.

Generated

Every remaining Action1 API operation as a verb-first snake_case tool; input parameter names are normalised to snake_case. See docs/api-coverage.md.

Destructive guard

A tool flagged destructiveHint: true executes only when all of these hold:

ACTION1_ALLOW_DESTRUCTIVE=true    server env, restart required
ACTION1_ALLOW_ACCOUNT_OPS=true    server env, only for account operations
confirm: "YES"                    per call, exact (waived by auto-confirm)
dry_run: false                    per call, the default is true (preview)

// Preview only (default)
{ "tool": "action1_run_powershell",
  "arguments": { "endpoint_id": "<uuid>", "script_text": "Get-Date" } }
// -> { "dry_run": true, "would_send": { method, path, body } }

// Execute (server env: ACTION1_ALLOW_DESTRUCTIVE=true)
{ "tool": "action1_run_powershell",
  "arguments": { "endpoint_id": "<uuid>", "script_text": "Get-Date",
                 "dry_run": false, "confirm": "YES" } }

confirm and dry_run are arguments the model sets itself. They stop accidents, not a model that follows instructions hidden in Action1 data (hostnames, script output, audit texts). The controls that hold against that are the ones the model cannot change: the environment switches, ACTION1_ALLOWED_ORG_IDS, ACTION1_TOOLSETS=read, the role of the API credential, and your MCP host's per-tool approval. Do not "always allow" destructive tools in your host. See docs/SECURITY.md for the threat model.

Examples

More in docs/EXAMPLES.md:

# 1. Fleet health check
> "How many endpoints are online and how many need a reboot?"
  agent -> action1_endpoints_summary

# 2. Read-only PowerShell on one Windows host
> "What's the OS build of <hostname>? Run Get-ComputerInfo OsBuildNumber."
  agent -> action1_search_endpoints { query: "<hostname>", fields: ["hostname"] }
  agent -> action1_run_powershell { endpoint_id: <uuid>,
             script_text: "Get-ComputerInfo OsBuildNumber",
             dry_run: false, confirm: "YES" }
  agent -> action1_wait_for_automation { instance_id: <id>, endpoint_id: <uuid> }

# 3. CVE remediation plan
> "What's needed to remediate CVE-2024-XXXX?"
  agent -> action1_cve_remediation_plan { cve_id: "CVE-2024-XXXX" }
  agent -> action1_deploy_update { ... }   (after operator confirmation)

Rate limits

Action1 does not publish a rate limit. During development about 10 requests per second on the EU instance did not trigger HTTP 429; that is an observation, not a guarantee. If Action1 answers 429:

• The client honours Retry-After (capped at 60 s), for reads and mutations alike, because a 429 means the request was not processed.
• For mass actions prefer target_type: "EndpointGroup" over one call per endpoint; Action1 fans out server-side.

The server has no outgoing throttle and does not cache list responses. The retry policy is in src/client/action1Client.ts.

Required Action1 permissions

The tools can only do what the role of the API credential allows. docs/permissions.md lists the permission each operation needs, generated from the permission tags in the pinned spec. Grant only what the tools you use need. Read action1://me or run the /check-my-permissions prompt to see what the configured credential can do before an agent tries a destructive operation.

Documentation

Development

npm run dev               # tsx watch (stdio)
npm run typecheck         # source
npm run typecheck:tests   # tests (tsconfig.test.json)
npm run lint
npm test                  # all test categories
npm run test:unit
npm run test:integration  # MCP protocol round trips
npm run test:security     # destructive-guard truth table, redaction
npm run test:performance  # size limits and rendering at scale
npm run test:coverage     # tests with the coverage thresholds from vitest.config.ts
npm run test:e2e          # builds the MCPB bundle, starts the built servers over stdio
npm run check             # lint, both typechecks, format check, tests (what CI gates on)
npm run codegen           # regenerate src/tools/generated/index.ts from the spec
npm run spec:check        # compare the pinned spec with the one Action1 serves
npm run inspector         # MCP Inspector against the built stdio server

The macOS payload-builder tests are deliberately strict: they protect the reverse-engineered field set. If you change the payload, update the test.

Roadmap

Open candidates (see also docs/api-coverage-gaps.md):

• Publish to npm with provenance.
• Live validation of the destructive tools listed under Validation status on a test endpoint.
• A Cloudflare Workers deployment of the HTTP transport.

Security

See docs/SECURITY.md. Report vulnerabilities through a private security advisory at https://github.com/mguttmann/action1-mcp/security/advisories/new, not in a public issue.

License

MIT © 2026 mguttmann, with one exception: the vendored Action1 API specification in src/codegen/spec/openapi.json belongs to Action1 Corporation and is not covered by the MIT License. See NOTICE.

Acknowledgements

• The MCP community at https://modelcontextprotocol.io.
• Anthropic's mcp-builder guide, which shaped the tool design and the evaluation format.
• The other open-source Action1 integrations whose code I read while scoping this one, in particular dimer47/action1-cli, pts211/action1-mcp-server and ghively/Action1MCP.