# clawops MCP server

> Provisions and manages self-hosted OpenClaw instances on AWS, GCP, Azure, or local VMs using typed MCP tools and safe infrastructure operations.

- Repository: https://github.com/dfridkin/clawops
- Page: https://hostedmcp.org/servers/dfridkin/clawops
- Transport: stdio
- Stars: 6
- License: MPL-2.0
- Latest version: 2.5.0

## Install

### Claude Code

```sh
claude mcp add clawops -- npx -y @clawops/cli
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "clawops": {
      "command": "npx",
      "args": [
        "-y",
        "@clawops/cli"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "clawops": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@clawops/cli"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"clawops","type":"stdio","command":"npx","args":["-y","@clawops/cli"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "clawops": {
      "command": "npx",
      "args": [
        "-y",
        "@clawops/cli"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add clawops -- npx -y @clawops/cli
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.clawops]
command = "npx"
args = ["-y", "@clawops/cli"]
```

### Gemini CLI

```sh
gemini mcp add -s user clawops npx -- -y @clawops/cli
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "clawops": {
      "command": "npx",
      "args": [
        "-y",
        "@clawops/cli"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `AWS_PROFILE` | no | no |  |

## Tools (30)

- `clawops_status`: Get what is deployed for a clawops-managed stack: public IP, gateway URL, SSH user, or that nothing is deployed yet. Reads stack outputs, and asks the host only for requests its host agent left for the operator (pendingHandoffs): each is a clawops command to show the user as it is. A request clears when that command is run, or after 7 days. Use when: the user asks what exists for a stack, where to reach it, or whether its agent is waiting on them. Do NOT use when: the user asks whether the gateway is actually WORKING — that needs the host, so use clawops_doctor. Also not for live logs (use clawops_logs_tail) or config values (use clawops_config_get). (read-only)
- `clawops_doctor`: Run clawops's diagnostics and return the report: Node and Pulumi runtime, config, SSH key and known_hosts, cloud credentials per configured provider, and the supported OpenClaw range. With stackName, also contacts the host for container state, the deployed OpenClaw version, a real gateway health probe, whether the port is published to the internet, disk usage on the state directory, log rotation, and hardening drift. Use when: something is not working and you do not yet know what; before any deploy, upgrade or migration; or to find out which OpenClaw version a gateway is actually running. Do NOT use when: you already know the problem and want to fix it. This tool only reports — it changes nothing, and never runs `openclaw doctor --fix`. To move a gateway to another version, use clawops_gateway_update after clawops_backup_create. Every check carries a status: fail (something is wrong that clawops can name), warn (worth knowing, not broken), info (did not apply). `ok` is false only when something failed — a fresh machine with no stacks is full of warnings and healthy. (read-only)
- `clawops_logs_tail`: Tail recent gateway logs from a clawops-managed instance. Use when: the user wants to investigate recent activity or errors, or asks "what's been happening" on the gateway. Do NOT use when: the user wants real-time streaming logs (those are not well-suited to tool calls; suggest the user run `clawops logs -f` directly in their terminal). Do NOT use for instance-level system logs: no tool runs arbitrary remote commands, so tell the user to run `clawops ssh --command 'journalctl ...'` themselves. (read-only)
- `clawops_monitor`: Take a live snapshot of a running clawops stack: gateway health, container status, resource usage (CPU, memory, disk), and recent log lines. Use when: the user wants to know if the gateway is running, how much memory or CPU it is using, what recent log activity looks like, or wants a quick health overview richer than clawops_status. Do NOT use when: the user wants real-time streaming logs (use clawops_logs_tail or suggest `clawops logs -f`). Do NOT use for configuration queries (use clawops_config_get). (read-only)
- `clawops_config_get`: Read a configuration value from the remote OpenClaw gateway. Use when: the user wants to inspect current OpenClaw config (e.g., which model provider is active, which channels are enabled). Do NOT use when: the user wants to change the config — use clawops_config_set instead. (read-only)
- `clawops_agents_list`: List agents currently registered on the remote OpenClaw gateway. Use when: the user wants to see which agents are running, debug agent routing, or count active workspaces. Do NOT use when: the user wants one agent's activity — that is clawops_agents_logs. (read-only)
- `clawops_agents_logs`: One agent's recent activity, read from the gateway's audit log, newest last. Paginated: pass the returned cursor to continue. Use when: the user asks what a specific agent did, or why it behaved as it did. Do NOT use when: the user wants the gateway's own log stream — that is clawops_logs_tail. Do NOT use to find agent names — that is clawops_agents_list. (read-only)
- `clawops_gateway_status`: Whether the OpenClaw gateway container is running, when it started, and which image it runs, as docker reports it on the host. Use when: the user asks whether the gateway is up or which OpenClaw version is deployed. Do NOT use when: the user wants a full health check — clawops_doctor probes the gateway itself rather than the container. Do NOT use to change anything; this only reads. (read-only)
- `clawops_secret_list`: List the secrets clawops stores locally, by name and status. Never returns a value. Use when: the user asks which secrets are set, or before a deploy that references one. Do NOT use when: the user wants to set or rotate a secret. No tool does that, because the value would pass through the conversation (R6): ask the user to run `clawops secret set <NAME>` or `clawops secret rotate <NAME>` in a terminal. (read-only)
- `clawops_secret_audit`: Report secrets that stacks reference but clawops does not have, and `$secret:` references that cannot be resolved. Never returns a value. Use when: a deploy or config change fails on a missing secret, or before applying a plan whose config references secrets. Do NOT use when: the user wants to set the missing secret — ask them to run `clawops secret set <NAME>` in a terminal; no tool takes a secret value (R6). (read-only)
- `clawops_up`: Provision and deploy a clawops stack. Idempotent — re-running with no spec change produces no diff. Long-running (median 3min, p99 8min) so emits progress notifications per R12. Use when: the user explicitly asks to deploy, provision, create, or "spin up" a stack. Always after the user has reviewed a plan (clawops_plan first when in doubt). Do NOT use when: the user has not yet generated a plan and is in exploratory/discovery mode — use clawops_plan first. Do NOT use for an existing stack you only need to update; refresh first.
- `clawops_destroy`: Destroy a clawops stack. Removes ALL provisioned resources. Triggers elicitation confirmation showing the resource diff before execution (R19). Cannot be undone. Use when: the user explicitly asks to destroy, tear down, delete, or remove a stack. Always confirm the stack name. Do NOT use when: the user wants to stop the gateway temporarily — that is not a destroy, and no tool stops a gateway; clawops_gateway_restart restarts it. Do NOT use when in doubt about which stack; list first with clawops_stacks_list.
- `clawops_apply`: Apply a previously-generated Maker plan (deploy-plan.schema.json). Deterministic — the plan describes exactly what will be created. Use when: the user has a plan file path and wants to apply it. This is the agent-friendly path for any deploy/destroy operation. Do NOT use when: there's no plan file — generate one first with clawops_plan.
- `clawops_plan`: Generate a Maker deploy plan (does NOT apply). Plan is JSON conforming to deploy-plan.schema.json — review before applying. Use when: the user wants to see what would be created before committing, or you (the agent) need a reviewable artifact for the user to approve. Do NOT use when: the user has explicitly asked to deploy and you already have their approval — go directly to clawops_up. (read-only)
- `clawops_config_set`: Set a configuration value on the remote OpenClaw gateway. Optionally restarts the gateway after. Use when: the user wants to change OpenClaw configuration (model provider, channel auth, gateway port). Do NOT use when: the user is reading config — use clawops_config_get. Do NOT bulk-edit; one key at a time so changes are auditable (R21).
- `clawops_config_unset`: Remove a configuration key from the remote OpenClaw gateway config, reverting it to the OpenClaw default. Use when: the user wants to delete a config key entirely (e.g., remove a channel, clear an override). Do NOT use when: the user wants to set the key to a new value — use clawops_config_set instead.
- `clawops_config_validate`: Validate the remote OpenClaw gateway config against the known schema. Checks for structural errors (wrong types, unknown top-level keys) that would cause OpenClaw to fail on startup. Use when: the user wants to verify config before restarting the gateway, or after editing openclaw.json manually. Do NOT use when: the user wants to change config — use clawops_config_set. (read-only)
- `clawops_gateway_restart`: Restart the OpenClaw gateway daemon on the remote instance. Use when: a gateway-wide config change requires reload, or the gateway is reported as unresponsive. Note: OpenClaw 2.0 removed per-agent restart; `gateway restart` is the only restart it offers, and it affects every agent on the host. Brief downtime (~10s).
- `clawops_gateway_update`: Move the gateway to a different OpenClaw version: pull the image and restart the gateway on it. Every agent on the host restarts with it. Use when: the user asks to upgrade or downgrade OpenClaw on a running stack, naming a version. Do NOT use when: the user has not named a concrete version — moving tags such as `latest` are refused, as the CLI refuses them. Do NOT use without a backup the user can return to: suggest clawops_backup_create first.
- `clawops_backup_create`: Take a backup of the gateway's state (config, database, sessions, transcripts and installed plugins) and download it to a local archive. Live state is not changed. Use when: the user asks for a backup, and before anything that replaces state: a version update, a migration, a restore, or a plan that replaces the instance. Do NOT use when: the user wants to back up cloud infrastructure — Pulumi state and plans cover that, not this.
- `clawops_backup_restore`: Verify a backup archive and expand it on the host beside the live state, never over it. With activate: true, also put it into service: stop the gateway, swap the restored state in (keeping the state it replaces), restart, and roll back if the gateway does not answer. Use when: the user asks to restore or recover from a backup, naming the archive. Do NOT use when: the gateway is merely unhealthy — clawops_workflow_recover diagnoses that without discarding state. Restoring is time travel: everything since the backup is lost, and channel credentials may need relinking.
- `clawops_migrate`: Move a deployment from OpenClaw 1.x onto the 2.0 runtime contract: state ownership, config, and the gateway's run command, in the order a real migration showed works. Use when: a stack still runs OpenClaw 1.x and the user wants it on 2.x. clawops_doctor and clawops_gateway_status say which line a stack runs. Do NOT use when: the stack is already on 2.x — use clawops_gateway_update to change versions within 2.x. Take a backup first with clawops_backup_create.
- `clawops_secret_delete`: Delete a locally stored secret by name. Warns when a stack still references it. Use when: the user asks to remove a secret they no longer use. Do NOT use when: the user wants to replace a value — ask them to run `clawops secret rotate <NAME>`; no tool takes a secret value (R6).
- `clawops_init`: Register a stack and write ~/.clawops/config.json: the provider, the state backend, the region, and an SSH key pair generated if one is not already there. Nothing is provisioned and nothing is charged; this only creates local configuration. Use when: any other clawops tool reports that there is no config, or the user wants to add a second stack alongside the ones they have. This is the first call on a machine that has never run clawops — a fresh container, a new laptop, a sandbox. Adding a stack is additive and safe: existing stacks are kept. Overwriting one needs force: true, because changing a state backend orphans the Pulumi state it points at — the infrastructure stays up and clawops can no longer see or destroy it. For aws, gcp and azure, stateUrl can be omitted and clawops names a bucket from the account it can see; that needs cloud credentials in the environment, so in a sandbox pass stateUrl explicitly. The local provider needs host instead, and no cloud account at all. Do NOT use when: the user wants to deploy — that is clawops_up, after this. Credentials are never passed here: clawops reads them from the environment (R6).
- `clawops_harden`: Apply security hardening to a deployed stack: SSH, UFW, fail2ban, unattended-upgrades, the Docker socket, and per-cloud checks. Optionally join the stack to a Tailscale network and reach it there instead of over the public internet. Use when: the user asks to harden, secure, or lock down a stack; asks what the hardening report says (with dryRun: true, which changes nothing); or asks to put a stack on their tailnet. tailscale: true installs Tailscale, joins the tailnet as clawops-<stack>, and then moves clawops onto that address — but only after opening an SSH session to it, against host keys pinned over the connection already trusted. If that fails, nothing is recorded and the public address stays in use. The auth key comes from `clawops secret set TAILSCALE_AUTH_KEY` and is never passed through this tool (R6). tailscaleRevert: true takes the host back off the tailnet, over its public address. On a private-only stack it refuses and names the plan/apply commands that reopen SSH first — relay them rather than trying to work around it. To close the public ports afterwards, plan with privateOnly: true and apply that plan; this tool does not change firewall rules. Do NOT use when: the user wants to know whether a stack is healthy — that is clawops_doctor. Do NOT pass tailscale and tailscaleRevert together.
- `clawops_task_status`: Poll the status of a long-running clawops task (returned by clawops_up, clawops_destroy, clawops_apply, etc.). Per R12 streaming model. Use when: the user is waiting on a long-running deploy/destroy and wants progress, OR you need to check whether a previously-started operation finished. Do NOT use when: there is no active taskId — start the operation first. (read-only)
- `clawops_workflow_deploy_app`: Single-tool workflow that takes a user from "I want to deploy OpenClaw to <provider>" to a verified, healthy gateway. Internally: plan → user confirms (elicitation) → up → wait for healthy → return URL. Use when: the user expresses end-to-end deployment intent ("deploy to AWS", "spin up an OpenClaw on GCP for me"). Do NOT use when: the user is mid-deployment and only needs one step (e.g., they already have a plan; use clawops_apply). Do NOT use for destroying or updating — separate workflows.
- `clawops_workflow_recover`: Diagnostic workflow for an unhealthy stack. Internally: what is deployed (clawops_status) → the stack's failed health checks (clawops_doctor) → the gateway's last 50 log lines (clawops_logs_tail) → a report with next steps that name the tool for each kind of failure. Changes nothing. Use when: the user reports any "not working" symptom and you don't know where to start. Best entry point for troubleshooting. Do NOT use when: the user has already identified the problem and asks for a specific fix. (read-only)
- `clawops_stacks_list`: List all clawops-managed stacks across all configured providers. With fleet: true, also reads every stack's host over SSH and reports its host agent: whether one is installed and running, which OpenClaw agent it serves, and, on a fleet member (ADR 0015), its tag, its peers, its firewall table and its tailnet state. Peers that cannot work are reported on the host that names them: a peer with no host agent, one that does not serve peers, one that answers a tag this host does not carry, or one reached by a name it does not have on the tailnet. Same reading as `clawops fleet status`. Changes nothing. On a host agent: this host and its fleet peers, and whether each peer answered. With fleet: true it reads this host and asks each peer to report itself, then checks them against each other the same way. A peer answers for itself only. Use when: the user wants an overview of their deployments, asks "what stacks do I have", or wants to compare stacks before an operation. With fleet: true, when they ask which host agents are running, whether the fleet is healthy, or why one host agent cannot reach another. Do NOT use when: the user named a specific stack — use clawops_status directly with that name. Do NOT pass fleet: true just to list stacks: it connects to every host and takes up to 30 s for one that does not answer. (read-only)
- `clawops_stacks_delete`: Remove a stack from ~/.clawops/config.json. This forgets the stack; it does not tear down its infrastructure, and it refuses a stack that is still deployed unless forced. Use when: the user wants to stop tracking a stack whose resources are already gone. Do NOT use when: the user wants the infrastructure removed — that is clawops_destroy, first. Forcing the delete of a deployed stack leaves resources running and billing that clawops can no longer see.

## FAQ

### Where are cloud credentials stored?

clawops never stores cloud credentials; it reads them from your environment's existing CLI profiles.

### Does clawops support Kubernetes?

No, clawops is optimized for single-node deployments to VMs rather than container orchestration platforms.

### Can I use clawops with Claude Code or Cursor?

Yes, it provides typed MCP tools that allow AI agents like Claude Code and Cursor to drive infrastructure operations safely.

### Is there a way to prevent accidental destructive actions via MCP?

Yes, you can start with read-only mode to enable diagnostics while blocking mutations, and destructive tools require explicit confirmation.
