Skip to main content
Glama

Read from the Hetzner API

hetzner_query
Read-onlyIdempotent

Run read-only JavaScript against Hetzner Cloud and Robot APIs to chain GET requests and filter responses in code, returning only the fields you need.

Instructions

Run JavaScript that reads from the Hetzner API. Only GET requests are possible, so nothing can be changed. Chain several calls and filter the data in the code instead of returning whole responses.

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.

Examples: async () => (await hetzner.paginate('/servers')).map(s => ({ id: s.id, name: s.name, status: s.status, type: s.server_type.name, ip: s.public_net.ipv4?.ip, location: s.datacenter?.location?.name })) async () => (await hetzner.get('/servers', { label_selector: 'env=prod', status: ['running'] })).servers.length async () => (await robot.get('/server')).map(({ server: s }) => ({ number: s.server_number, name: s.server_name, ip: s.server_ip, product: s.product, dc: s.dc })) async () => (await robot.get('/firewall/321')).firewall async () => { const [servers, volumes] = await Promise.all([hetzner.paginate('/servers'), hetzner.paginate('/volumes')]); return volumes.filter(v => !v.server).map(v => ({ id: v.id, name: v.name, size: v.size })); }

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_query"
  }
}

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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.1

TDQS

B3.4/5.0
Behavior1/5

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

The opening says only GET requests are possible and nothing can be changed, which aligns with readOnlyHint=true. However, the globals section then advertises hetzner.post/put/delete and robot.post/put/delete as available, implying write capability and directly conflicting with the read-only annotations. This is a serious safety inconsistency despite the otherwise rich behavioral detail.

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?

The description is long but well structured for a complex code-execution tool, with the core purpose front-loaded and useful sections for globals, constraints, and examples. Some redundancy and the contradictory write-helper listing keep it from being fully clean.

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

Completeness4/5

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

For a complex open-world query tool with no output schema, the description covers API roots, validation, pagination, errors, Robot limitations, and examples. The main completeness gap is the ambiguity around whether post/put/delete are actually available, which leaves the read-only boundary unclear.

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 coverage is 100%, so the schema already documents both parameters, and the description adds substantial meaning for the code parameter by defining the available globals, examples, error shape, and validation behavior. The project parameter gets some additional context about selected projects and Robot ignoring project, though not enough to warrant a top score.

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

Purpose4/5

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

The description states a specific verb and resource: run JavaScript that reads from the Hetzner API, with GET-only behavior. That clearly distinguishes it from a write-oriented sibling like hetzner_execute, but it does not explicitly differentiate itself from hetzner_search or explain when that sibling would be preferred.

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

Usage Guidelines4/5

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

It gives clear usage context: use it for reads, chain calls, and filter in code rather than returning whole responses. It also states the GET-only limitation and Robot unavailability, but it never names an alternative tool for writes or search, so the when-not guidance is implicit rather than explicit.

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