Skip to main content
Glama

Change resources through the Hetzner API

hetzner_execute
Destructive

Execute validated JavaScript to create, update, or delete Hetzner Cloud and Robot resources; billed and destructive requests require explicit approval before sending.

Instructions

Run JavaScript that changes Hetzner resources (POST, PUT, DELETE as well as GET). Changes are real and immediate: they can create billable resources, cause downtime or delete data permanently. Through robot this includes ordering and cancelling dedicated servers, hardware resets, and firewall rules that can lock everyone out of a server (POST /firewall/{server-number} replaces the whole rule set: read it first and send all rules back, except output rules named "Block mail ports", which Hetzner prepends itself and would duplicate; the update is asynchronous, poll until status is no longer "in process"). Look the operation up with hetzner_search first, use hetzner_query for pure reads, and act only on resources the user named.

Guard: requests that cost money (creating servers, volumes, load balancers, IPs, snapshots, Storage Boxes, type changes, backups, Robot orders) are refused unless the operator switched billed requests on. Billed requests and destructive ones (every DELETE, rebuilding a server, disabling backups, importing a zone file, Robot cancellations and OS installations) are not sent on the first attempt: the result states what they do and the price. Report that to the user and wait for their answer.

Globals available in the code: hetzner.request({ method = 'GET', path, query?, body?, api? }) -> parsed JSON body (null if empty) hetzner.get(path, query?) / hetzner.post(path, body?) / hetzner.put(path, body?) / hetzner.delete(path) hetzner.paginate(path, query?, { maxPages = 50 }?) -> all items of a list endpoint across pages hetzner.waitForAction(actionOrResponse, { timeoutMs = 90000 }?) -> finished action, throws if it failed sleep(ms), console.log(...) robot.get(path, query?) / robot.post(path, body?) / robot.put(path, body?) / robot.delete(path) / robot.request({...}) Paths are relative to the API root, e.g. "/servers/123" (no host, no /v1). Storage Box paths are routed to api.hetzner.com automatically. Array query values become repeated keys. Failed calls throw an Error with .status, .code and .details. No fetch, require or other network access exists. Every request is checked against the API reference before it is sent (operation exists, known query and body fields, required fields, types, enum values); a mismatch throws with code "validation_failed" and nothing is sent. Only if the reference itself is wrong: hetzner.request({ ..., validate: false }). hetzner is the Cloud API of the selected project. robot is the Robot webservice for dedicated servers (NOT available: no Robot webservice user is configured); it is account-wide and ignores project. Robot paths are singular ("/server", "/firewall/{server-number}"), have no pagination and no actions, and are rate limited per endpoint (see "Request limit" in describe()). Pass Robot bodies as plain objects; they are sent form-encoded, nested values become rules[input][0][action]=accept.

Most Cloud changes return an "action" that runs asynchronously; await hetzner.waitForAction(response) before relying on the result.

Examples: async () => { const res = await hetzner.post('/servers/123/actions/reboot'); return await hetzner.waitForAction(res); } async () => { const res = await hetzner.post('/servers', { name: 'web-1', server_type: 'cx23', image: 'ubuntu-24.04', location: 'nbg1', ssh_keys: ['my-key'] }); await hetzner.waitForAction(res); return { id: res.server.id, ip: res.server.public_net.ipv4.ip }; }

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "code": "<code>"
    },
    "name": "hetzner_execute"
  }
}

Input Schema

NameRequiredDescriptionDefault
codeYesJavaScript: an async arrow function whose return value is the result. Return only the fields you need.
projectNoHetzner Cloud project to use. Only needed when several projects are available.
confirmedNoSet true only after the user approved the billed or destructive requests of exactly this code. Without it such requests are not sent; the result says what they would do and cost.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.1

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructiveHint=true and openWorldHint=true, but the description goes far beyond: it names the concrete harms (billable resources, downtime, permanent data loss), documents the billed-request guard and the two-step confirm flow via `confirmed`, describes pre-flight validation against the API reference with the `validation_failed` code, async action polling, Robot rate limits, and the absence of fetch/require. This is unusually rich behavioral disclosure for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the most consequential warning (real, immediate, billable changes), then guards, then the runtime API surface, then examples — a sensible ordering. It is long, and the Robot form-encoding parenthetical and the firewall rule-set caveat are dense digressions, but nearly every sentence carries operational information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool that is effectively a sandboxed HTTP client, the description covers the runtime globals, path conventions, error shape, validation behavior, async action handling, and worked examples. There is no output schema, and the description compensates by stating what calls return (parsed JSON, null when empty) and what waitForAction yields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline would be 3. The description still adds meaning: it clarifies that `project` selects which Cloud API `hetzner` binds to and that Robot ignores it, and it expands `confirmed` into an approval protocol ('after the user approved the billed or destructive requests of exactly this code') rather than a bare boolean. It does not restate the `code` contract in any new detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a concrete verb+resource: 'Run JavaScript that changes Hetzner resources (POST, PUT, DELETE as well as GET).' It immediately distinguishes the read case by naming the siblings: 'use hetzner_query for pure reads' and 'Look the operation up with hetzner_search first.' An agent can route between the three tools without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing rules ('use hetzner_query for pure reads'), a sequencing rule ('Look the operation up with hetzner_search first'), and a scoping constraint ('act only on resources the user named'). It also enumerates exactly which request classes are gated and the required confirmation handshake, so the agent knows when not to send.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools