the-real-hetzner-mcp
Provides typed tools covering the Hetzner Cloud API, including read and write operations for Hetzner Cloud resources such as servers and Cloud DNS zones/RRSets. Includes hand-tuned server-operation wrappers, a raw request escape hatch, pagination, action polling, and optional write-confirmation, read-only, and tool-denial safeguards.
the-real-hetzner-mcp
An unofficial local Model Context Protocol (MCP) server
(stdio) for the Hetzner Cloud API: every operation of the vendored Hetzner Cloud API
specification as a typed tool, read and write, plus hand-tuned wrappers for the common server
operations. npm package: @mguttmann/hetzner-cloud-mcp.
Unofficial project. This server is not affiliated with, endorsed by, sponsored by or
supported by Hetzner Online GmbH. "Hetzner" is a trademark of Hetzner Online GmbH. The vendored
API specification (specs/cloud.spec.json) is Hetzner's and is not covered by this project's
MIT License. See NOTICE.
Maintenance status
Maintained on a best-effort basis by one maintainer (@mguttmann) in spare time. There is no support contract and no guaranteed response time.
Security fixes take priority over features. Report vulnerabilities privately through GitHub private vulnerability reporting, never in a public issue; see SECURITY.md.
Only the latest minor release gets fixes (SECURITY.md lists the supported versions).
Dependency updates come from Dependabot; CI fails when a runtime dependency has a known high or critical advisory.
Releases are built and published by GitHub Actions from a tag on
main, with a CycloneDX SBOM,SHA256SUMSand build provenance (CHANGELOG.md lists the changes).Issues and pull requests are welcome. Tool names, parameters and environment variables are kept stable between releases; see AGENTS.md for the contract rules.
Related MCP server: hetzner-mcp
Features
Full coverage of the Hetzner Cloud API via codegen from
specs/cloud.spec.json(one generated tool per operation), plus hand-tuned wrappers for the common server operations. The exact tool list and count are pinned bytests/tools-contract.test.tsagainsttests/snapshots/tools-contract.json.hcloud_raw_requestas a generic escape hatch for any endpoint.Capped 429 backoff, automatic pagination with a soft-cap, action polling with a wall-clock budget (see Timeouts and retries).
Optional write guard
HETZNER_CONFIRM_WRITES=true: every tool that is not read-only returns a preview (tool name and input) unless the call carriesconfirm: "YES".Optional operator switches
HETZNER_READ_ONLY=true(only read-only tools andGETthroughhcloud_raw_requestrun) andHETZNER_DENY_TOOLS(tool name globs that always return an error). Both leave the tool list and the schemas unchanged.
Out of Scope
Not covered: Hetzner Robot (the dedicated-server API), Hetzner DNS (the standalone DNS product, a separate API from Cloud DNS) and Hetzner Storage Boxes. They are not part of the Cloud API and the codegen has no spec for them.
Covered: Cloud DNS zones and RRSets (/v1/zones) are part of the Cloud API spec, so they are in scope through the generated tools.
Installation
Requires Node.js 22.12 or newer (engines in package.json; the CI matrix in .github/workflows/ci.yml tests the floor and the current Node lines).
Do not install 0.1.x. npm versions below 0.2.0 (0.1.0 and 0.1.1) are affected by a path-injection vulnerability that is fixed in 0.2.0, see SECURITY.md.
From npm (0.2.0 or newer)
The package name is exactly @mguttmann/hetzner-cloud-mcp; packages with similar names are not from this project.
npm install -g "@mguttmann/hetzner-cloud-mcp@>=0.2.0"The version range makes npm refuse the vulnerable 0.1.x versions. If npm reports that no matching version exists, 0.2.0 is not published yet: install from a pinned git commit instead. In your MCP client config the command is then just hetzner-cloud-mcp (no path needed).
With npx (no global install)
npx -y "@mguttmann/hetzner-cloud-mcp@>=0.2.0"MCP clients start it the same way, see Variant C. Keep the version range: without it npx would take whatever version npm serves as latest.
From the MCP Registry
Once listed, the server is in the official MCP Registry as io.github.mguttmann/the-real-hetzner-mcp, with the npm package above as its package. Clients that install from the registry use the same npm package.
From a pinned git commit
git clone https://github.com/mguttmann/the-real-hetzner-mcp.git
cd the-real-hetzner-mcp
git checkout <full commit sha>
npm ci
npm run buildPin a full commit SHA, not a branch name: the commit of the v0.2.0 tag (git rev-list -n 1 v0.2.0) or a later commit on main. npm ci installs exactly the committed lockfile.
Setup
With the npm package, set the variables in the env block of your MCP client configuration (see MCP Connector Setup); the package ships no .env file. In a git checkout:
cp .env.example .env
# Add HETZNER_API_TOKEN to .env (Read & Write token from the Hetzner Cloud Console)npm run refresh-spec and npm run generate are not part of the setup: they change the tool surface (see Spec Updates).
The server reads its configuration from the environment. At startup it also loads the .env file in the package directory (next to package.json, dotenv), never one from the current working directory; variables that are already set win. A deployment can pass the file explicitly instead, from any working directory: node --env-file=/path/to/.env dist/index.js.
Optional smoke test against the real API (four read-only calls):
npm run test:liveConfiguration
Only HETZNER_API_TOKEN is required. The defaults below are pinned by tests/config.test.ts. A numeric value that is not a positive number, and an unknown boolean or log level, falls back to the default. Exceptions that stop the server at startup instead: an invalid HETZNER_API_BASE and an unknown HETZNER_READ_ONLY value.
Variable | Default | Meaning |
| (required) | Hetzner Cloud API token, sent as a bearer token on every request. The server can do exactly what this token allows. |
|
| API base URL. Must be |
|
|
|
|
|
|
| (empty) | Comma-separated tool name globs ( |
|
|
|
|
| Wall-clock budget for one API request, all attempts and retry delays included. |
|
| Longest single retry delay. A 429 whose |
|
| Wall-clock budget of a |
|
| Pause between two polls. The |
|
| Soft cap on the items an auto-paginated list collects; a capped list reports |
|
| Soft cap on the pages an auto-paginated list requests. |
|
| Largest tool result text in bytes, counted as sent (JSON-escaped). A longer result is cut and ends with |
|
| Wall-clock budget of one auto-paginated list. When it ends, the pages read so far come back with |
|
|
|
Development only: RUN_LIVE_TESTS=1 enables tests/live-smoke.test.ts (set by npm run test:live), and HETZNER_LIVE_SMOKE_ANCHORS optionally names servers that test expects to find.
Timeouts and retries
Retries: a 429 is retried after Retry-After, or after a short backoff when the header is
missing (Hetzner refills one request per second; RateLimit-Reset is the time the bucket is
full again and is not used as a delay). A 5xx is retried with backoff, except for POST, which
may already have been processed. With the defaults one tool call answers within about
max(HTTP_TIMEOUT_MS, ACTION_POLL_TIMEOUT_MS) (tests/call-budget.test.ts measures this), so it
stays below a 60 s client call timeout, common in MCP clients and gateways. Keep that relation if you
raise the values. Auto-paginated lists run one request per page within
PAGINATION_TIMEOUT_MS; when that budget ends, the pages read so far come back with
truncated: true and a note, never as a list that looks complete.
When polling fails or the budget runs out after a successful write, the tool returns the write
response (for example the new resource id and a one-time root_password) with
polling_timed_out: true, plus polling_error if polling failed.
MCP protocol
The server speaks MCP over stdio only and opens no network port.
Protocol revisions: a client that asks for
2024-11-05,2025-03-26,2025-06-18or2025-11-25gets that revision back; a client that asks for a newer one (for example2026-07-28) ininitializegets2025-11-25(tests/server.test.ts).2026-07-28 is opt-in: with
MCP_SERVE_MODERN_PROTOCOL=truethe server also answers a client that opens withserver/discoverand serves it the 2026-07-28 revision, with the same tools. A client that opens withinitializestill gets the 2025-era session above (tests/serve-protocol.test.ts). The default isfalse: a client in auto mode (such as the pythonmcpclient) would switch to the new revision as soon as it is offered, so turn it on only after checking the client. Seedocs/adr/0001-mcp-sdk-v2.md.Message size limit: one inbound JSON-RPC message (one stdin line) may be at most 10 MiB, the MCP SDK's stdio limit (
tests/transport-lifecycle.test.ts). A longer line closes the transport: the server logsmcp transport erroron stderr and exits with code 1. Keep large arguments (for exampleuser_data) well below that size. Outbound, a tool result is cut atMAX_OUTPUT_BYTES(at most 8 MiB,tests/output-cap.test.ts) and then ends with an[output truncated by MAX_OUTPUT_BYTES=...]marker.
MCP Connector Setup (Claude Desktop / Claude Code)
Append to your client's MCP config (~/Library/Application Support/Claude/claude_desktop_config.json for Claude Desktop, or the equivalent in Claude Code).
Variant A: installed via npm
{
"mcpServers": {
"hetzner-cloud": {
"command": "hetzner-cloud-mcp",
"env": {
"HETZNER_API_TOKEN": "...",
"HETZNER_CONFIRM_WRITES": "false",
"LOG_LEVEL": "warn"
}
}
}
}Variant B: from a git checkout
{
"mcpServers": {
"hetzner-cloud": {
"command": "node",
"args": ["/absolute/path/to/the-real-hetzner-mcp/dist/index.js"],
"env": {
"HETZNER_API_TOKEN": "...",
"HETZNER_CONFIRM_WRITES": "false",
"LOG_LEVEL": "warn"
}
}
}
}Variant C: with npx
{
"mcpServers": {
"hetzner-cloud": {
"command": "npx",
"args": ["-y", "@mguttmann/hetzner-cloud-mcp@>=0.2.0"],
"env": {
"HETZNER_API_TOKEN": "...",
"HETZNER_CONFIRM_WRITES": "false",
"LOG_LEVEL": "warn"
}
}
}
}Restart the client to pick up the change. tools/list should expose the tools pinned in tests/snapshots/tools-contract.json, all named hcloud_*.
Tools: overview
Hand-tuned Wrappers
Tool | What it does |
| Server list with |
| Fetch a server by |
| poweron / poweroff / reboot / shutdown / reset in a single tool. |
| Rebuild a server, |
|
|
| Toggle automatic backups. |
| Toggle rescue mode, default |
| Change server type, default |
| Server metrics, |
| Apply a firewall to a server, by-id OR by-name. |
| Arbitrary request against the API. Query parameters go in |
| Poll an action until success/error or timeout. |
Generated Tools
One tool per OpenAPI operation, naming scheme hcloud_<verb>_<resource> or hcloud_<resource>_<action>_action. On name collision with a wrapper the generated tool gets the suffix _raw (hcloud_list_servers_raw, hcloud_get_server_raw, hcloud_get_server_metrics_raw).
Run tools/list in the Inspector to see the full list.
Input Validation
Arguments are checked against the tool's declared inputSchema before the
handler runs. The low-level MCP SDK server validates only the shape of the
tools/call request, so this check is what makes the advertised schema binding.
A violation returns an isError result naming the offending property; the
handler is not invoked and no request reaches the Hetzner API.
What is enforced:
Resource ids must be JSON integers >= 1. String-encoded numbers such as
"42"are rejected rather than coerced. Path parameters that the API declares as strings (id_or_name,rr_name,rr_type) stay strings, but a string used in the path has to name a single segment, see below.Top-level types,
enum,minimum/maximum,minLength/maxLengthand flat array elements (element type,items.enum,items.minimum/maximum), plusrequired. For a parameter declared as an array of scalars a bare scalar is also accepted and checked against the element schema: for a repeatable query parameter such assortorstatusit serialises to exactly the same single parameter, so rejecting it would break a call that has always worked. The one array-typed parameter that goes into a request body,hcloud_server_rescue.ssh_keys, normalises the scalar into a one-element array, so the value a caller sends is always used or refused, never silently dropped. Per-element messages for a bad array are capped at the first 10 plus a count (tests/validate-input.test.ts), so a large input cannot be amplified into the result or the log.Unknown top-level properties, for the tools whose schema declares
additionalProperties: false(all wrappers and all generated tools). The out-of-band keysconfirm,waitandauto_paginateare always tolerated, so sendingconfirmwhileHETZNER_CONFIRM_WRITESis disabled, orwait/auto_paginateto a tool that does not declare them, is not an error; those keys are dropped before the request is built.A path parameter must name exactly one path segment. For the parameters the API declares as strings (
id_or_name,rr_name) the value is rejected if it is empty, is.or.., contains/or\, or contains a percent-encoded separator or dot (%2f,%5c,%2ein any casing). Reason: percent-encoding keeps such a value inside one segment only as far as the local URL parser is concerned. The actor that resolves the path is the origin, which decodes encoded separators and resolves dot segments before routing, so without this check a crafted value could address a different resource than the tool's own. Legitimate values are untouched: IDN zone names (raw or punycode), a trailing dot,@,*,*.sub,_dmarcand the like all pass and are percent-encoded as before.Path segments are percent-encoded at every interpolation site, and the HTTP client refuses any path that URL normalisation would change. Rejected:
?and#(which truncate the path into query/fragment),\(a path separator to the URL parser), characters outside RFC 3986pcharsuch as control characters (which the parser strips, so they could otherwise form a dot segment), empty segments, and./..segments in every spelling, including the percent-encoded ones. The assembled URL is then compared against the intended target: its origin must be the configured one and its path must equal the base path plus the requested path exactly, so any remaining normalisation aborts the request instead of redirecting it. This client-side check only sees what the local URL parser would rewrite, so it is the last line of defence, not the whole guarantee: the per-parameter rule above is what covers what the origin would rewrite.Rejected input produces no HTTP request at all, not a sanitised one.
What is deliberately not enforced: the contents of a request body. Those
trees are the Hetzner Cloud API's own contract: it validates them and its 400
responses are surfaced to the caller unchanged. format, pattern and
nullable are not evaluated either.
Validation failures are logged with the offending property name and the type
of the offending value; the value itself is only quoted back to the caller, so a
malformed body carrying a private key or password does not end up in the log.
Note on hcloud_raw_request: it remains a deliberate escape hatch that accepts
any path by design, so it is not constrained to a resource whitelist. It is
pinned to the configured API base URL (origin and path prefix), but a caller
granted this tool can reach any endpoint of the Hetzner Cloud API. Like every
other tool it rejects a percent-encoded separator or dot (%2F, %5C, %2E in
any casing) in its path, because the origin, not the local URL parser, decides
what an encoded separator means. Grant hcloud_raw_request accordingly.
Spec Updates
When Hetzner updates the OpenAPI:
npm run refresh-spec # re-downloads specs/cloud.spec.json
# update the fetch date and the SHA-256 in specs/SOURCE.md
npm run generate # rebuilds src/tools/generated/operations.ts
npm test # codegen and contract snapshots show the diff
npm run refresh-snapshot # rewrite the snapshots deliberately (after review)
git add specs/cloud.spec.json specs/SOURCE.md src/tools/generated/operations.ts tests/snapshots/tool-registry.json tests/snapshots/tools-contract.json
git commit -m "chore(spec): refresh from Hetzner"A refresh changes tool input schemas and can add tools, which MCP clients and gateways see as
a contract change. List it under "Behaviour changes" in CHANGELOG.md. If the new spec makes a
body field of an existing tool required, keep the old list in PINNED_BODY_REQUIRED in
scripts/generate.ts, so the tool contract does not tighten; the API still rejects a call that
lacks the field. A new tool changes the tool count and name hash of the gateway baseline,
which live in one file, tests/gateway-baseline.json, read by tests/tools-contract.test.ts
and by the CI and release smoke.
Development
Tool contract snapshot
tests/tools-contract.test.ts builds the registry exactly as the stdio server does
(src/build-registry.ts) and compares every tool against tests/snapshots/tools-contract.json:
name, inputSchema.required, a sha256 of the canonical (key-sorted) JSON of inputSchema
(with and without HETZNER_CONFIRM_WRITES=true), a sha256 of the description, and the
annotations. It also pins the tool count and the sha256 of the sorted tool names to the
gateway baseline; those two values live in tests/gateway-baseline.json and are not rewritten by
any script.
npm run refresh-snapshot regenerates both tests/snapshots/tool-registry.json and
tests/snapshots/tools-contract.json. Run it only for a deliberate contract change and review
the diff: a changed required, schema or description hash changes what MCP clients see.
Stdio smoke test
npm run smoke spawns dist/index.js (run npm run build first), sends initialize,
notifications/initialized and tools/list over stdio, and prints the negotiated protocol
version, serverInfo, the tool count and the sha256 of the sorted tool names as JSON. It needs
no network:
HETZNER_API_TOKEN=dummy HETZNER_API_BASE=http://127.0.0.1:1 npm run smoke -- \
--min-tools <n> --expect-names-sha256 <sha256>
# or with an env file, passed to node as --env-file:
npm run smoke -- --env-file ./smoke.envOptions: --protocol-version <v>, --min-tools <n>, --expect-names-sha256 <hex>,
--baseline <file> (sets both from a JSON file with toolCount and namesSha256),
--server <path> (default dist/index.js) and --timeout-ms <ms>; the defaults are at the top
of scripts/smoke-stdio.mjs. Exit code 0 means all checks passed, 1 a check failed, 2 the
server did not start or answer. CI runs it with --baseline tests/gateway-baseline.json, the file
tests/tools-contract.test.ts also reads.
Manual Verification Recipe
Run before declaring a release ready:
npm run inspectoropens the MCP Inspector with this server.tools/list: verify the count equalstoolCountintests/snapshots/tools-contract.jsonand that every wrapper in the table above appears.hcloud_list_servers(no args): verify against at least one known server in your account.hcloud_get_serverwithname: "<one of your server names>": should return id, type, ip.hcloud_create_ssh_keywith{ name: "mcp-smoke", public_key: "<your test key>" }: note the returned id.hcloud_delete_ssh_keywith that id: confirm clean removal.
Do not run power/rebuild/snapshot operations against production servers as part of a smoke test.
Security
See SECURITY.md for supported versions, how to report a vulnerability privately and the threat model (token authority, the confirm guard, grants by tool name).
License
MIT, see LICENSE, except the vendored Hetzner Cloud API specification
(specs/cloud.spec.json), which is Hetzner's; see NOTICE and
specs/SOURCE.md.
Available Tools
202 toolshcloud_apply_firewall_to_serverBDestructive
Apply a firewall (by id or by name) to a server. Hand-tuned wrapper around POST /firewalls/{id}/actions/apply_to_resources.
Inputs: server_id (required), firewall_id, firewall_name.
hcloud_certificate_retry_actionA
Retry Issuance or Renewal
Retry a failed Certificate issuance or renewal.
Only applicable if the type of the Certificate is managed and the issuance or renewal status is failed.
Operation specific errors
Status | Code | Description |
| CAA record does not allow certificate authority | |
| Certificate Authority: DNS validation failed | |
| Certificate Authority: Too many authorizations failed recently | |
| Certificate Authority: Too many certificates issued for registered domain | |
| Certificate Authority: Too many duplicate certificates | |
| Could not verify domain delegated to zone | |
| DNS zone not found | |
| DNS zone is a secondary zone |
Inputs: id (required), wait.
hcloud_create_certificateA
Create a Certificate
Creates a new Certificate.
The default type uploaded allows for uploading your existing certificate and private_key in PEM format. You have to monitor its expiration date and handle renewal yourself.
In contrast, type managed requests a new Certificate from Let's Encrypt for the specified domain_names. Only domains managed by Hetzner DNS are supported. We handle renewal and timely alert the project owner via email if problems occur.
For type managed Certificates the action key of the response contains the Action that allows for tracking the issuance process. For type uploaded Certificates the action is always null.
Inputs: body (required), wait.
hcloud_create_firewallC
Inputs: body (required).
hcloud_create_floating_ipB
Create a Floating IP
Create a Floating IP.
Provide the server attribute to assign the Floating IP to that server or provide a home_location to locate the Floating IP at. Note that the Floating IP can be assigned to a Server in any Location later on. For optimal routing it is advised to use the Floating IP in the same Location it was created in.
Inputs: body (required), wait.
hcloud_create_load_balancerC
Create a Load Balancer
Creates a Load Balancer.
Operation specific errors
Status | Code | Description |
|
| The source port you are trying to add is already in use |
|
| The specified Primary IP has the wrong IP version |
|
| The IP is not owned by the owner of the project of the Load Balancer |
|
| The Load Balancer is not attached to a network |
|
| The server you are trying to add as a target is not attached to the same network as the Load Balancer |
|
| The server that you are trying to add as a public target does not have a public IPv4 address |
|
| The Load Balancer target you are trying to define is already defined |
|
| The specified Primary IP is already assigned to a resource |
|
| The specified Primary IP is blocked |
|
| The specified Primary IP is bound to a different Location than the Load Balancer |
Inputs: body (required), wait.
hcloud_create_networkA
Create a Network
Creates a Network.
The provided ip_range can only be extended later on, but not reduced.
Subnets can be added now or later on using the add subnet action. If you do not specify an ip_range for the subnet the first available /24 range will be used.
Routes can be added now or later by using the add route action.
Inputs: body (required).
hcloud_create_placement_groupC
Create a PlacementGroup
Creates a new Placement Group.
Inputs: body (required), wait.
hcloud_create_primary_ipA
Create a Primary IP
Create a new Primary IP.
Can optionally be assigned to a resource by providing an assignee_id and assignee_type.
If not assigned to a resource the location key needs to be provided. This can be either the ID or the name of the Location this Primary IP shall be created in.
A Primary IP can only be assigned to resource in the same Location later on.
Operation specific errors
Inputs: body (required), wait.
hcloud_create_serverB
Create a Server
Creates a new Server. Returns preliminary information about the Server as well as an Action that covers progress of creation.
Operation specific errors
Status | Code | Description |
|
| The specified Primary IP has the wrong IP Version |
|
| An error during the placement occurred |
|
| The specified Primary IP is already assigned to a server |
|
| The specified Primary IP is in a different location |
Inputs: body (required), wait.
hcloud_create_ssh_keyB
Create an SSH key
Creates a new SSH key with the given name and public_key. Once an SSH key is created, it can be used in other calls such as creating Servers.
Inputs: body (required).
hcloud_create_volumeA
Create a Volume
Creates a new Volume attached to a Server. If you want to create a Volume that is not attached to a Server, you need to provide the location key instead of server. This can be either the ID or the name of the Location this Volume will be created in. Note that a Volume can be attached to a Server only in the same Location as the Volume itself.
Specifying the Server during Volume creation will automatically attach the Volume to that Server after it has been initialized. In that case, the next_actions key in the response is an array which contains a single attach_volume action.
The minimum Volume size is 10GB and the maximum size is 10TB (10240GB).
A volume’s name can consist of alphanumeric characters, dashes, underscores, and dots, but has to start and end with an alphanumeric character. The total length is limited to 64 characters. Volume names must be unique per Project.
Operation specific errors
Status | Code | Description |
|
| There is no volume space left in the given location |
Inputs: body (required), wait.
hcloud_create_zoneB
Create a Zone
Creates a Zone.
A default SOA and three NS resource records with the assigned Hetzner
nameservers are created automatically.
Inputs: body (required), wait.
hcloud_delete_certificateCDestructive
Delete a Certificate
Deletes a Certificate.
Inputs: id (required).
hcloud_delete_firewallADestructive
hcloud_delete_floating_ipADestructive
Delete a Floating IP
Deletes a Floating IP.
If assigned to a Server the Floating IP will be unassigned automatically until 1 May 2026. After this date, the Floating IP needs to be unassigned before it can be deleted.
Operation specific errors
Status | Code | Description |
|
| Error when IP is still assigned to a Resource. This error will appear as of 1 May 2026. |
Inputs: id (required).
hcloud_delete_imageADestructive
Delete an Image
Deletes an Image. Only Images of type snapshot and backup can be deleted.
Inputs: id (required).
hcloud_delete_load_balancerCDestructive
Delete a Load Balancer
Deletes a Load Balancer.
Inputs: id (required), wait.
hcloud_delete_networkBDestructive
Inputs: id (required).
hcloud_delete_placement_groupCDestructive
Delete a PlacementGroup
Deletes a Placement Group.
Inputs: id (required).
hcloud_delete_primary_ipADestructive
Delete a Primary IP
Deletes a Primary IP.
The Server must be powered off (status off) in order for this operation to succeed.
If assigned to a Server the Primary IP will be unassigned automatically until 1 May 2026. After this date, the Primary IP needs to be unassigned before it can be deleted.
Operation specific errors
Status | Code | Description |
|
| Error when IP is still assigned to a Resource. This error will appear as of 1 May 2026. |
Inputs: id (required).
hcloud_delete_serverBDestructive
Delete a Server
Deletes a Server.
This immediately removes the Server from your account, and it is no longer accessible. Any resources attached to the server (like Volumes, Primary IPs, Floating IPs, Firewalls, Placement Groups) are detached while the server is deleted.
Inputs: id (required), wait.
hcloud_delete_ssh_keyBDestructive
Delete an SSH key
Deletes an SSH key. It cannot be used anymore.
Inputs: id (required).
hcloud_delete_volumeADestructive
Delete a Volume
Deletes a volume. All Volume data is irreversibly destroyed. The Volume must not be attached to a Server and it must not have delete protection enabled.
Inputs: id (required).
hcloud_delete_zoneCDestructive
Delete a Zone
Deletes a Zone.
Inputs: id_or_name (required), wait.
hcloud_delete_zone_rrsetADestructive
hcloud_firewall_apply_to_resources_actionADestructive
Apply to Resources
Applies a Firewall to multiple resources.
Supported resources:
Servers (with a public network interface)
A Server can be applied to a maximum of 5 Firewalls. This limit applies to Servers applied via a matching Label Selector as well.
Updates to resources matching or no longer matching a Label Selector can take up to a few seconds to be processed.
A Firewall is applied to a resource once the related Action with command apply_firewall successfully finished.
Operation specific errors
Status | Code | Description |
|
| The resource the Firewall should be applied to was not found |
|
| Firewall is already applied to resource |
|
| The network type of the resource is not supported by Firewalls |
|
| The Server the Firewall should be applied to has no public interface |
Inputs: id (required), body (required).
hcloud_firewall_remove_from_resources_actionADestructive
Remove from Resources
Removes a Firewall from multiple resources.
Supported resources:
Servers (with a public network interface)
A Firewall is removed from a resource once the related Action with command remove_firewall successfully finished.
Operation specific errors
Status | Code | Description |
|
| The resource the Firewall should be removed from was not found |
|
| Firewall is applied via a Label Selector and cannot be removed manually |
Inputs: id (required), body (required).
hcloud_firewall_set_rules_actionADestructive
Set Rules
Set the rules of a Firewall.
Overwrites the existing rules with the given ones. Pass an empty array to remove all rules.
Rules are limited to 50 entries per Firewall and 500 effective rules.
Inputs: id (required), body (required).
hcloud_floating_ip_assign_actionCDestructive
Assign a Floating IP to a Server
Assigns a Floating IP to a Server.
Operation specific errors
Status | Code | Description |
|
| The Floating IP is already assigned |
Inputs: id (required), body (required), wait.
hcloud_floating_ip_change_dns_ptr_actionCDestructive
Change reverse DNS records for a Floating IP
Change the reverse DNS records for this Floating IP.
Allows to modify the PTR records set for the IP address.
Inputs: id (required), body (required), wait.
hcloud_floating_ip_change_protection_actionCDestructive
Change Floating IP Protection
Changes the protection settings configured for the Floating IP.
Inputs: id (required), body (required), wait.
hcloud_floating_ip_unassign_actionADestructive
Unassign a Floating IP
Unassigns a Floating IP.
Results in the IP being unreachable. Can be assigned to another resource again.
Inputs: id (required), wait.
hcloud_get_actionCRead-only
Get an Action
Returns a specific Action object.
Inputs: id (required), wait.
hcloud_get_certificateCRead-only
Get a Certificate
Gets a specific Certificate object.
Inputs: id (required).
hcloud_get_certificate_actionARead-only
Get an Action for a Certificate
Deprecated: This operation is deprecated, see our changelog for more details.
Returns a specific Action for a Certificate. Only type managed Certificates have Actions.
Inputs: id (required), action_id (required), wait.
hcloud_get_certificates_actionsCRead-only
List Actions
Returns all Action objects. You can sort the results by using the sort URI parameter, and filter them with the status and id parameter.
Inputs: id, page, sort, status, +1 more.
hcloud_get_certificates_actions_idCRead-only
Get an Action
Returns a specific Action object.
Inputs: id (required), wait.
hcloud_get_datacenterARead-only
Get a Data Center
Deprecated: This endpoint is deprecated as of 01 June 2026 and will be removed after 01 October 2026.
Returns a single Data Center.
Inputs: id (required).
hcloud_get_firewallCRead-only
Get a Firewall
Returns a single Firewall.
Inputs: id (required).
hcloud_get_firewall_actionARead-only
hcloud_get_firewalls_actionsCRead-only
hcloud_get_firewalls_actions_idCRead-only
Get an Action
Returns the specific Action.
Inputs: id (required), wait.
hcloud_get_floating_ipBRead-only
Get a Floating IP
Returns a single Floating IP.
Inputs: id (required).
hcloud_get_floating_ip_actionBRead-only
Get an Action for a Floating IP
Deprecated: This operation is deprecated, see our changelog for more details.
Returns a specific Action for a Floating IP.
Inputs: id (required), action_id (required), wait.
hcloud_get_floating_ips_actionsCRead-only
Inputs: id, page, sort, status, +1 more.
hcloud_get_floating_ips_actions_idCRead-only
Get an Action
Returns a single Action.
Inputs: id (required), wait.
hcloud_get_imageCRead-only
Get an Image
Returns a specific Image object.
Inputs: id (required).
hcloud_get_image_actionARead-only
Get an Action for an Image
Deprecated: This operation is deprecated, see our changelog for more details.
Returns a specific Action for an Image.
Inputs: id (required), action_id (required), wait.
hcloud_get_images_actionsCRead-only
List Actions
Returns all Action objects. You can sort the results by using the sort URI parameter, and filter them with the status and id parameter.
Inputs: id, page, sort, status, +1 more.
hcloud_get_images_actions_idCRead-only
Get an Action
Returns a specific Action object.
Inputs: id (required), wait.
hcloud_get_isoCRead-only
Get an ISO
Returns a specific ISO object.
Inputs: id (required).
hcloud_get_load_balancerCRead-only
Get a Load Balancer
Gets a specific Load Balancer object.
Inputs: id (required).
hcloud_get_load_balancer_actionARead-only
Get an Action for a Load Balancer
Deprecated: This operation is deprecated, see our changelog for more details.
Returns a specific Action for a Load Balancer.
Inputs: id (required), action_id (required), wait.
hcloud_get_load_balancer_metricsARead-only
Get Metrics for a LoadBalancer
You must specify the type of metric to get: open_connections, connections_per_second, requests_per_second or bandwidth. You can also specify more than one type by comma separation, e.g. requests_per_second,bandwidth.
Depending on the type you will get different time series data:
Type | Timeseries | Unit | Description |
open_connections | open_connections | number | Open connections |
connections_per_second | connections_per_second | connections/s | Connections per second |
requests_per_second | requests_per_second | requests/s | Requests per second |
bandwidth | bandwidth.in | bytes/s | Ingress bandwidth |
bandwidth.out | bytes/s | Egress bandwidth |
Metrics are available for the last 30 days only.
If you do not provide the step argument we will automatically adjust it so that 200 samples are returned.
We limit the number of samples to a maximum of 500 and will adjust the step parameter accordingly.
Inputs: id (required), end (required), type (required), start (required), +1 more.
hcloud_get_load_balancers_actionsCRead-only
List Actions
Returns all Action objects. You can sort the results by using the sort URI parameter, and filter them with the status and id parameter.
Inputs: id, page, sort, status, +1 more.
hcloud_get_load_balancers_actions_idCRead-only
Get an Action
Returns a specific Action object.
Inputs: id (required), wait.
hcloud_get_load_balancer_typeCRead-only
Get a Load Balancer Type
Gets a specific Load Balancer type object.
Inputs: id (required).
hcloud_get_locationCRead-only
Get a Location
Returns a Location.
Inputs: id (required).
hcloud_get_networkCRead-only
Get a Network
Get a specific Network.
Inputs: id (required).
hcloud_get_network_actionARead-only
hcloud_get_network_membersBRead-only
List Members of a Network
List the resources attached to a specific Network.
Use the provided URI parameters to modify the result.
Inputs: id (required), page, sort, type, +3 more.
hcloud_get_networks_actionsCRead-only
Inputs: id, page, sort, status, +1 more.
hcloud_get_networks_actions_idCRead-only
Get an Action
Returns a single Action.
Inputs: id (required), wait.
hcloud_get_placement_groupCRead-only
Get a PlacementGroup
Gets a specific Placement Group object.
Inputs: id (required).
hcloud_get_pricingARead-only
Get all prices
Returns prices for all resources available on the platform. VAT and currency of the Project owner are used for calculations.
Both net and gross prices are included in the response.
Inputs: auto_paginate.
hcloud_get_primary_ipCRead-only
Get a Primary IP
Returns a Primary IP.
Inputs: id (required).
hcloud_get_primary_ip_actionARead-only
Get an Action for a Primary IP
Deprecated: This operation is deprecated, see our changelog for more details.
Returns a specific Action for a Primary IP.
Inputs: id (required), action_id (required), wait.
hcloud_get_primary_ips_actionsCRead-only
Inputs: id, page, sort, status, +1 more.
hcloud_get_primary_ips_actions_idCRead-only
Get an Action
Returns a single Action.
Inputs: id (required), wait.
hcloud_get_serverARead-only
Fetch a single Hetzner Cloud server by numeric id OR by exact name. Hand-tuned wrapper; use hcloud_get_server_raw for the id-only generated tool.
Inputs: id, name.
hcloud_get_server_actionBRead-only
Get an Action for a Server
Deprecated: This operation is deprecated, see our changelog for more details.
Returns a specific Action object for a Server.
Inputs: id (required), action_id (required), wait.
hcloud_get_server_metricsBRead-only
Fetch a server's metrics (cpu / disk / network). Accept id OR name. Defaults to the last hour with step=60s. Hand-tuned wrapper.
Inputs: type (required), id, end, name, +2 more.
hcloud_get_server_metrics_rawARead-only
Get Metrics for a Server
Get Metrics for specified Server.
You must specify the type of metric to get: cpu, disk or network. You can also specify more than one type by comma separation, e.g. cpu,disk.
Depending on the type you will get different time series data
Type | Timeseries | Unit | Description |
cpu | cpu | percent | Percent CPU usage |
disk | disk.0.iops.read | iop/s | Number of read IO operations per second |
disk.0.iops.write | iop/s | Number of write IO operations per second | |
disk.0.bandwidth.read | bytes/s | Bytes read per second | |
disk.0.bandwidth.write | bytes/s | Bytes written per second | |
network | network.0.pps.in | packets/s | Public Network interface packets per second received |
network.0.pps.out | packets/s | Public Network interface packets per second sent | |
network.0.bandwidth.in | bytes/s | Public Network interface bytes/s received | |
network.0.bandwidth.out | bytes/s | Public Network interface bytes/s sent |
Note that the CPU value is not normalized to a fixed 0-100% scale. It is calculated per vCPU: a value of 100 represents full utilization on a 1-vCPU server, and 25% utilization on a 4-vCPU server. To calculate the overall CPU usage, divide the metric value by the number of vCPUs.
Metrics are available for the last 30 days only.
If you do not provide the step argument we will automatically adjust it so that a maximum of 200 samples are returned.
We limit the number of samples returned to a maximum of 500 and will adjust the step parameter accordingly.
Inputs: id (required), end (required), type (required), start (required), +1 more.
hcloud_get_server_rawBRead-only
Get a Server
Returns a specific Server object. The Server must exist inside the Project.
Inputs: id (required).
hcloud_get_servers_actionsCRead-only
List Actions
Returns all Action objects. You can sort the results by using the sort URI parameter, and filter them with the status and id parameter.
Inputs: id, page, sort, status, +1 more.
hcloud_get_servers_actions_idCRead-only
Get an Action
Returns a specific Action object.
Inputs: id (required), wait.
hcloud_get_server_typeCRead-only
Get a Server Type
Gets a specific Server type object.
Inputs: id (required).
hcloud_get_ssh_keyCRead-only
Get a SSH key
Returns a specific SSH key object.
Inputs: id (required).
hcloud_get_volumeCRead-only
Get a Volume
Gets a specific Volume object.
Inputs: id (required).
hcloud_get_volume_actionARead-only
Get an Action for a Volume
Deprecated: This operation is deprecated, see our changelog for more details.
Returns a specific Action for a Volume.
Inputs: id (required), action_id (required), wait.
hcloud_get_volumes_actionsCRead-only
List Actions
Returns all Action objects. You can sort the results by using the sort URI parameter, and filter them with the status and id parameter.
Inputs: id, page, sort, status, +1 more.
hcloud_get_volumes_actions_idCRead-only
Get an Action
Returns a specific Action object.
Inputs: id (required), wait.
hcloud_get_zoneCRead-only
Get a Zone
Returns a single Zone.
Inputs: id_or_name (required).
hcloud_get_zone_actionARead-only
hcloud_get_zone_rrsetARead-only
hcloud_get_zone_rrsetsARead-only
List RRSets
Returns all RRSets in the Zone.
Use the provided URI parameters to modify the result.
Only applicable for Zones in primary mode.
Operation specific errors
Status | Code | Description |
|
| This operation is not supported for this Zone's |
Inputs: id_or_name (required), name, page, sort, +3 more.
hcloud_get_zones_actionsBRead-only
hcloud_get_zones_actions_idCRead-only
Get an Action
Returns a specific Action.
Inputs: id (required), wait.
hcloud_get_zone_zonefileARead-only
hcloud_image_change_protection_actionBDestructive
Change Image Protection
Changes the protection configuration of the Image. Can only be used on snapshots.
Inputs: id (required), body (required), wait.
hcloud_list_actionsARead-only
Get multiple Actions
Returns multiple Action objects specified by the id parameter.
Note: This endpoint previously allowed listing all actions in the project. This functionality was deprecated in July 2023 and removed on 30 January 2025.
Inputs: id (required), auto_paginate.
hcloud_list_certificate_actionsARead-only
List Actions for a Certificate
Returns all Action objects for a Certificate. You can sort the results by using the sort URI parameter, and filter them with the status parameter.
Only type managed Certificates can have Actions. For type uploaded Certificates the actions key will always contain an empty array.
Inputs: id (required), page, sort, status, +2 more.
hcloud_list_certificatesCRead-only
List Certificates
Returns all Certificate objects.
Inputs: name, page, sort, type, +3 more.
hcloud_list_datacentersARead-only
List Data Centers
Deprecated: This endpoint is deprecated as of 01 June 2026 and will be removed after 01 October 2026.
Returns all Data Centers.
Inputs: name, page, sort, per_page, +1 more.
hcloud_list_firewall_actionsCRead-only
hcloud_list_firewallsBRead-only
Inputs: name, page, sort, per_page, +2 more.
hcloud_list_floating_ip_actionsBRead-only
List Actions for a Floating IP
Lists Actions for a Floating IP.
Use the provided URI parameters to modify the result.
Inputs: id (required), page, sort, status, +2 more.
hcloud_list_floating_ipsBRead-only
Inputs: name, page, sort, per_page, +2 more.
hcloud_list_image_actionsARead-only
List Actions for an Image
Returns all Action objects for an Image. You can sort the results by using the sort URI parameter, and filter them with the status parameter.
Inputs: id (required), page, sort, status, +2 more.
hcloud_list_imagesBRead-only
List Images
Returns all Image objects. You can select specific Image types only and sort the results by using URI parameters.
Inputs: name, page, sort, type, +7 more.
hcloud_list_isosCRead-only
List ISOs
Returns all available ISO objects.
Inputs: name, page, per_page, architecture, +2 more.
hcloud_list_load_balancer_actionsARead-only
List Actions for a Load Balancer
Returns all Action objects for a Load Balancer. You can sort the results by using the sort URI parameter, and filter them with the status parameter.
Inputs: id (required), page, sort, status, +2 more.
hcloud_list_load_balancersBRead-only
List Load Balancers
Gets all existing Load Balancers that you have available.
Inputs: name, page, sort, per_page, +2 more.
hcloud_list_load_balancer_typesCRead-only
List Load Balancer Types
Gets all Load Balancer type objects.
Inputs: name, page, per_page, auto_paginate.
hcloud_list_locationsCRead-only
List Locations
Returns all Locations.
Inputs: name, page, sort, per_page, +1 more.
hcloud_list_network_actionsCRead-only
hcloud_list_networksCRead-only
Inputs: name, page, sort, per_page, +2 more.
hcloud_list_placement_groupsCRead-only
List Placement Groups
Returns all Placement Group objects.
Inputs: name, page, sort, type, +3 more.
hcloud_list_primary_ip_actionsBRead-only
List Actions for a Primary IP
Returns all Actions for a Primary IP.
Use the provided URI parameters to modify the result.
Inputs: id (required), page, sort, status, +2 more.
hcloud_list_primary_ipsCRead-only
Inputs: ip, name, page, sort, +3 more.
hcloud_list_server_actionsBRead-only
List Actions for a Server
Returns all Action objects for a Server. You can sort the results by using the sort URI parameter, and filter them with the status parameter.
Inputs: id (required), page, sort, status, +2 more.
hcloud_list_serversARead-only
List Hetzner Cloud servers. Hand-tuned wrapper around GET /servers with an optional client-side name_contains filter and a default sort of 'name'. Use hcloud_list_servers_raw for the unfiltered, generator-built tool.
Inputs: page, sort, per_page, name_contains, +1 more.
hcloud_list_servers_rawCRead-only
List Servers
Returns all existing Server objects.
Inputs: name, page, sort, status, +3 more.
hcloud_list_server_typesCRead-only
List Server Types
Gets all Server type objects.
Inputs: name, page, per_page, auto_paginate.
hcloud_list_ssh_keysBRead-only
List SSH keys
Returns all SSH key objects.
Inputs: name, page, sort, per_page, +3 more.
hcloud_list_volume_actionsARead-only
List Actions for a Volume
Returns all Action objects for a Volume. You can sort the results by using the sort URI parameter, and filter them with the status parameter.
Inputs: id (required), page, sort, status, +2 more.
hcloud_list_volumesCRead-only
List Volumes
Gets all existing Volumes that you have available.
Inputs: name, page, sort, status, +3 more.
hcloud_list_zone_actionsBRead-only
hcloud_list_zonesCRead-only
Inputs: mode, name, page, sort, +3 more.
hcloud_load_balancer_add_service_actionB
Add Service
Adds a service to a Load Balancer.
Operation specific errors
Status | Code | Description |
|
| The source port you are trying to add is already in use |
Inputs: id (required), body (required), wait.
hcloud_load_balancer_add_target_actionB
Add Target
Adds a target to a Load Balancer.
Operation specific errors
Status | Code | Description |
|
| The IP you are trying to add does not belong to the vswitch subnet of the attached network |
|
| The IP you are trying to add as a target is not owned by the Project owner |
|
| The specified IP is neither the Primary IPv4 address nor in the IPv6 subnet of the given Server |
|
| The Load Balancer's public network interface is disabled |
|
| The Load Balancer is not attached to a network |
|
| The given IP is private but attached network does not have a vswitch subnet |
|
| The server you are trying to add as a target is not attached to the same network as the Load Balancer |
|
| The server that you are trying to add as a public target does not have a public IPv4 address |
|
| The Load Balancer target you are trying to define is already defined |
Inputs: id (required), body (required), wait.
hcloud_load_balancer_attach_to_network_actionB
Attach a Load Balancer to a Network
Attach a Load Balancer to a Network.
Operation specific errors
Status | Code | Description |
|
| The Load Balancer is already attached to a network |
|
| The provided Network IP is not available |
|
| No Subnet or IP is available for the Load Balancer within the network |
Inputs: id (required), body (required), wait.
hcloud_load_balancer_change_algorithm_actionBDestructive
Change Algorithm
Change the algorithm that determines to which target new requests are sent.
Inputs: id (required), body (required), wait.
hcloud_load_balancer_change_dns_ptr_actionBDestructive
Change reverse DNS entry for this Load Balancer
Changes the hostname that will appear when getting the hostname belonging to the public IPs (IPv4 and IPv6) of this Load Balancer.
Floating IPs assigned to the Server are not affected by this.
Inputs: id (required), body (required), wait.
hcloud_load_balancer_change_protection_actionCDestructive
Change Load Balancer Protection
Changes the protection configuration of a Load Balancer.
Inputs: id (required), body (required), wait.
hcloud_load_balancer_change_type_actionBDestructive
Change the Type of a Load Balancer
Changes the type (Max Services, Max Targets and Max Connections) of a Load Balancer.
Operation specific errors
Status | Code | Description |
|
| The Load Balancer type does not fit for the given Load Balancer |
Inputs: id (required), body (required), wait.
hcloud_load_balancer_delete_service_actionCDestructive
Delete Service
Delete a service of a Load Balancer.
Inputs: id (required), body (required), wait.
hcloud_load_balancer_detach_from_network_actionCDestructive
Detach a Load Balancer from a Network
Detaches a Load Balancer from a network.
Inputs: id (required), body (required), wait.
hcloud_load_balancer_disable_public_interface_actionADestructive
Disable the public interface of a Load Balancer
Disable the public interface of a Load Balancer. The Load Balancer will be not accessible from the internet via its public IPs.
Operation specific errors
Status | Code | Description |
|
| The Load Balancer is not attached to a network |
|
| The Load Balancer has targets that use the public IP instead of the private IP |
Inputs: id (required), wait.
hcloud_load_balancer_enable_public_interface_actionBDestructive
Enable the public interface of a Load Balancer
Enable the public interface of a Load Balancer. The Load Balancer will be accessible from the internet via its public IPs.
Inputs: id (required), wait.
hcloud_load_balancer_remove_target_actionCDestructive
Remove Target
Removes a target from a Load Balancer.
Inputs: id (required), body (required), wait.
hcloud_load_balancer_update_service_actionBDestructive
Update Service
Updates a Load Balancer Service.
Operation specific errors
Status | Code | Description |
|
| The source port you are trying to add is already in use |
Inputs: id (required), body (required), wait.
hcloud_network_add_subnet_actionA
Add a subnet to a Network
Adds a new subnet to the Network.
If the subnet ip_range is not provided, the first available /24 IP range will be used.
If a change is currently being performed on this Network, a error response with code conflict will be returned.
Inputs: id (required), body (required), wait.
hcloud_network_change_ip_range_actionADestructive
Change IP range of a Network
Changes the IP range of a Network.
The following restrictions apply to changing the IP range:
IP ranges can only be extended and never shrunk.
IPs can only be added to the end of the existing range, therefore only the netmask is allowed to be changed.
To update the routes on the connected Servers, they need to be rebooted or the routes to be updated manually.
For example if the Network has a range of 10.0.0.0/16 to extend it the new range has to start with the IP 10.0.0.0 as well. The netmask /16 can be changed to a smaller one then 16 therefore increasing the IP range. A valid entry would be 10.0.0.0/15, 10.0.0.0/14 or 10.0.0.0/13 and so on.
If a change is currently being performed on this Network, a error response with code conflict will be returned.
Inputs: id (required), body (required), wait.
hcloud_network_change_protection_actionBDestructive
hcloud_network_delete_route_actionBDestructive
hcloud_network_delete_subnet_actionADestructive
Delete a subnet from a Network
Deletes a single subnet entry from a Network.
Subnets containing attached resources can not be deleted, they must be detached beforehand.
If a change is currently being performed on this Network, a error response with code conflict will be returned.
Inputs: id (required), body (required), wait.
hcloud_primary_ip_assign_actionADestructive
Assign a Primary IP to a resource
Assign a Primary IP to a resource.
A Server can only have one Primary IP of type ipv4 and one of type ipv6 assigned. If you need more IPs use Floating IPs.
A Server must be powered off (status off) in order for this operation to succeed.
Operation specific errors
Status | Code | Description |
|
| The Server is running, but needs to be powered off |
|
| Primary IP is already assigned to a different Server |
|
| The Server already has an IPv4 address |
|
| The Server already has an IPv6 address |
Inputs: id (required), body (required), wait.
hcloud_primary_ip_change_dns_ptr_actionCDestructive
Change reverse DNS records for a Primary IP
Change the reverse DNS records for this Primary IP.
Allows to modify the PTR records set for the IP address.
Inputs: id (required), body (required), wait.
hcloud_primary_ip_change_protection_actionBDestructive
Change Primary IP Protection
Changes the protection configuration of a Primary IP.
A Primary IPs deletion protection can only be enabled if its auto_delete property is set to false.
Inputs: id (required), body (required), wait.
hcloud_primary_ip_unassign_actionADestructive
Unassign a Primary IP from a resource
Unassign a Primary IP from a resource.
A Server must be powered off (status off) in order for this operation to succeed.
A Server requires at least one network interface (public or private) to be powered on.
Operation specific errors
Inputs: id (required), wait.
hcloud_raw_requestADestructive
Escape hatch: issue an arbitrary request against the Hetzner Cloud API. The configured API token is sent and the client retries a 429, and a 5xx on methods other than POST, like every other tool. Pagination and action polling are not applied, and an HTTP error comes back as { status, body } instead of an error result. Use only when no dedicated tool fits.
Inputs: path (required), method (required), body, query, +1 more.
hcloud_server_add_to_placement_group_actionA
Add a Server to a Placement Group
Adds a Server to a Placement Group.
Server must be powered off for this command to succeed.
Operation specific errors
Status | Code | Description |
|
| The action requires a stopped server |
|
| The server is already part of a placement group |
Inputs: id (required), body (required), wait.
hcloud_server_attach_iso_actionADestructive
Attach an ISO to a Server
Attaches an ISO to a Server. The Server will immediately see it as a new disk. An already attached ISO will automatically be detached before the new ISO is attached.
Servers with attached ISOs have a modified boot order: They will try to boot from the ISO first before falling back to hard disk.
Inputs: id (required), body (required), wait.
hcloud_server_attach_to_network_actionA
Attach a Server to a Network
Attaches a Server to a network. This will complement the fixed public Server interface by adding an additional ethernet interface to the Server which is connected to the specified network.
The Server will get an IP auto assigned from a subnet of type server in the same network_zone.
Using the alias_ips attribute you can also define one or more additional IPs to the Servers. Please note that you will have to configure these IPs by hand on your Server since only the primary IP will be given out by DHCP.
Operation specific errors
Status | Code | Description |
|
| The server is already attached to the network |
|
| The provided Network IP is not available |
|
| No Subnet or IP is available for the Server within the network |
|
| The network IP range overlaps with one of the server networks |
Inputs: id (required), body (required), wait.
hcloud_server_backupCDestructive
Toggle Hetzner-managed automatic backups on a server. Hand-tuned wrapper around enable_backup / disable_backup actions.
Inputs: id (required), enable (required), wait.
hcloud_server_change_alias_ips_actionADestructive
Change alias IPs of a Network
Changes the alias IPs of an already attached Network. Note that the existing aliases for the specified Network will be replaced with these provided in the request body. So if you want to add an alias IP, you have to provide the existing ones from the Network plus the new alias IP in the request body.
Inputs: id (required), body (required), wait.
hcloud_server_change_dns_ptr_actionADestructive
Change reverse DNS entry for this Server
Changes the hostname that will appear when getting the hostname belonging to the primary IPs (IPv4 and IPv6) of this Server.
Floating IPs assigned to the Server are not affected by this.
Inputs: id (required), body (required), wait.
hcloud_server_change_protection_actionCDestructive
Change Server Protection
Changes the protection configuration of the Server.
Inputs: id (required), body (required), wait.
hcloud_server_change_typeBDestructive
Change a server's hardware type. Defaults upgrade_disk to false (disk size kept; safer to downgrade later). Hand-tuned wrapper; polls the resulting action by default.
Inputs: id (required), server_type (required), wait, upgrade_disk.
hcloud_server_change_type_actionADestructive
Change the Type of a Server
Changes the type (Cores, RAM and disk sizes) of a Server.
Server must be powered off for this command to succeed.
This copies the content of its disk, and starts it again.
You can only migrate to Server types with the same storage_type and equal or bigger disks. Shrinking disks is not possible as it might destroy data.
If the disk gets upgraded, the Server type can not be downgraded any more. If you plan to downgrade the Server type, set upgrade_disk to false.
Operation specific errors
Status | Code | Description |
|
| The server type does not fit for the given server or is deprecated |
|
| The action requires a stopped server |
Inputs: id (required), body (required), wait.
hcloud_server_create_image_actionA
Create Image from a Server
Creates an Image (snapshot) from a Server by copying the contents of its disks. This creates a snapshot of the current state of the disk and copies it into an Image. If the Server is currently running you must make sure that its disk content is consistent. Otherwise, the created Image may not be readable.
To make sure disk content is consistent, we recommend to shut down the Server prior to creating an Image.
You can either create a backup Image that is bound to the Server and therefore will be deleted when the Server is deleted, or you can create a snapshot Image which is completely independent of the Server it was created from and will survive Server deletion. Backup Images are only available when the backup option is enabled for the Server. Snapshot Images are billed on a per GB basis.
Inputs: id (required), body (required), wait.
hcloud_server_detach_from_network_actionCDestructive
Detach a Server from a Network
Detaches a Server from a network. The interface for this network will vanish.
Inputs: id (required), body (required), wait.
hcloud_server_detach_iso_actionBDestructive
Detach an ISO from a Server
Detaches an ISO from a Server. In case no ISO Image is attached to the Server, the status of the returned Action is immediately set to success.
Inputs: id (required), wait.
hcloud_server_disable_backup_actionADestructive
Disable Backups for a Server
Disables the automatic backup option and deletes all existing Backups for a Server. No more additional charges for backups will be made.
Caution: This immediately removes all existing backups for the Server!
Inputs: id (required), wait.
hcloud_server_disable_rescue_actionADestructive
Disable Rescue Mode for a Server
Disables the Hetzner Rescue System for a Server. This makes a Server start from its disks on next reboot.
Rescue Mode is automatically disabled when you first boot into it or if you do not use it for 60 minutes.
Disabling rescue mode will not reboot your Server - you will have to do this yourself.
Inputs: id (required), wait.
hcloud_server_enable_backup_actionA
Enable and Configure Backups for a Server
Enables and configures the automatic daily backup option for the Server. Enabling automatic backups will increase the price of the Server by 20%. In return, you will get seven slots where Images of type backup can be stored.
Backups are automatically created daily.
Inputs: id (required), wait.
hcloud_server_enable_rescue_actionADestructive
Enable Rescue Mode for a Server
Enable the Hetzner Rescue System for this Server. The next time a Server with enabled rescue mode boots it will start a special minimal Linux distribution designed for repair and reinstall.
In case a Server cannot boot on its own you can use this to access a Server’s disks.
Rescue Mode is automatically disabled when you first boot into it or if you do not use it for 60 minutes.
Enabling rescue mode will not reboot your Server - you will have to do this yourself.
Inputs: id (required), body (required), wait.
hcloud_server_powerCDestructive
Run a power operation on a server (poweron / poweroff / reboot / shutdown / reset). Hand-tuned wrapper that polls the resulting action by default.
Inputs: id (required), op (required), wait.
hcloud_server_poweroff_actionADestructive
Power off a Server
Cuts power to the Server. This forcefully stops it without giving the Server operating system time to gracefully stop. May lead to data loss, equivalent to pulling the power cord. Power off should only be used when shutdown does not work.
Inputs: id (required), wait.
hcloud_server_poweron_actionC
Power on a Server
Starts a Server by turning its power on.
Inputs: id (required), wait.
hcloud_server_reboot_actionADestructive
Soft-reboot a Server
Reboots a Server gracefully by sending an ACPI request. The Server operating system must support ACPI and react to the request, otherwise the Server will not reboot.
Inputs: id (required), wait.
hcloud_server_rebuildBDestructive
Rebuild a server from an image. Accept image_id (integer) OR image_name (string). Hand-tuned wrapper; polls the resulting action by default.
Inputs: id (required), wait, image_id, image_name.
hcloud_server_rebuild_actionADestructive
Rebuild a Server from an Image
Rebuilds a Server overwriting its disk with the content of an Image, thereby destroying all data on the target Server
The Image can either be one you have created earlier (backup or snapshot Image) or it can be a completely fresh system Image provided by us. You can get a list of all available Images with GET /images.
Your Server will automatically be powered off before the rebuild command executes.
Inputs: id (required), body (required), wait.
hcloud_server_remove_from_placement_group_actionCDestructive
Remove from Placement Group
Removes a Server from a Placement Group.
Inputs: id (required), wait.
hcloud_server_request_console_actionADestructive
Request Console for a Server
Requests credentials for remote access via VNC over websocket to keyboard, monitor, and mouse for a Server. The provided URL is valid for 1 minute, after this period a new url needs to be created to connect to the Server. How long the connection is open after the initial connect is not subject to this timeout.
Inputs: id (required), wait.
hcloud_server_rescueBDestructive
Toggle Hetzner rescue mode on a server. When enabling, defaults type to 'linux64' and accepts ssh_keys (array of SSH-key ids). Hand-tuned wrapper.
Inputs: id (required), enable (required), type, wait, +1 more.
hcloud_server_reset_actionADestructive
Reset a Server
Cuts power to a Server and starts it again. This forcefully stops it without giving the Server operating system time to gracefully stop. This may lead to data loss, it’s equivalent to pulling the power cord and plugging it in again. Reset should only be used when reboot does not work.
Inputs: id (required), wait.
hcloud_server_reset_password_actionADestructive
Reset root Password of a Server
Resets the root password. Only works for Linux systems that are running the qemu guest agent. Server must be powered on (status running) in order for this operation to succeed.
This will generate a new password for this Server and return it.
If this does not succeed you can use the rescue system to netboot the Server and manually change your Server password by hand.
Inputs: id (required), wait.
hcloud_server_shutdown_actionADestructive
Shutdown a Server
Shuts down a Server gracefully by sending an ACPI shutdown request. The Server operating system must support ACPI
and react to the request, otherwise the Server will not shut down. Please note that the action status in this case
only reflects whether the action was sent to the server. It does not mean that the server actually shut down
successfully. If you need to ensure that the server is off, use the poweroff action.
Inputs: id (required), wait.
hcloud_server_snapshotB
Create an image (snapshot or backup) of a server. Default type is 'snapshot'. Hand-tuned wrapper that polls the resulting action.
Inputs: id (required), type, wait, labels, +1 more.
hcloud_update_certificateCDestructive
Update a Certificate
Updates the Certificate properties.
Note: if the Certificate object changes during the request, the response will be a “conflict” error.
Inputs: id (required), body (required).
hcloud_update_firewallBDestructive
hcloud_update_floating_ipCDestructive
Update a Floating IP
Update a Floating IP.
Inputs: id (required), body (required).
hcloud_update_imageADestructive
Update an Image
Updates the Image. You may change the description, convert a Backup Image to a Snapshot Image or change the Image labels. Only Images of type snapshot and backup can be updated.
Inputs: id (required), body (required).
hcloud_update_load_balancerBDestructive
Update a Load Balancer
Updates a Load Balancer. You can update a Load Balancer’s name and a Load Balancer’s labels.
Note: if the Load Balancer object changes during the request, the response will be a “conflict” error.
Inputs: id (required), body (required).
hcloud_update_networkCDestructive
hcloud_update_placement_groupCDestructive
Update a PlacementGroup
Updates the Placement Group properties.
Note: if the Placement Group object changes during the request, the response will be a “conflict” error.
Inputs: id (required), body (required).
hcloud_update_primary_ipCDestructive
Update a Primary IP
Update a Primary IP.
If another change is concurrently performed on this Primary IP, a error response with code conflict will be returned.
Inputs: id (required), body (required).
hcloud_update_serverBDestructive
Update a Server
Updates a Server. You can update a Server’s name and a Server’s labels.
Please note that Server names must be unique per Project and valid hostnames as per RFC 1123 (i.e. may only contain letters, digits, periods, and dashes).
Inputs: id (required), body (required).
hcloud_update_ssh_keyCDestructive
Update an SSH key
Updates an SSH key. You can update an SSH key name and an SSH key labels.
Inputs: id (required), body (required).
hcloud_update_volumeCDestructive
Update a Volume
Updates the Volume properties.
Inputs: id (required), body (required).
hcloud_update_zoneCDestructive
Update a Zone
Updates a Zone.
To modify resource record sets (RRSets), use the RRSet Actions endpoints.
Inputs: body (required), id_or_name (required).
hcloud_update_zone_rrsetADestructive
hcloud_volume_attach_actionA
Attach Volume to a Server
Attaches a Volume to a Server. Works only if the Server is in the same Location as the Volume.
Inputs: id (required), body (required), wait.
hcloud_volume_change_protection_actionCDestructive
Change Volume Protection
Changes the protection configuration of a Volume.
Inputs: id (required), body (required), wait.
hcloud_volume_detach_actionADestructive
Detach Volume
Detaches a Volume from the Server it’s attached to. You may attach it to a Server again at a later time.
Inputs: id (required), wait.
hcloud_volume_resize_actionBDestructive
Resize Volume
Changes the size of a Volume. Note that downsizing a Volume is not possible.
Inputs: id (required), body (required), wait.
hcloud_wait_actionARead-only
Poll an existing Hetzner Cloud action until it reaches terminal status (success/error) or the timeout elapses. Returns the final action plus a polling_timed_out flag.
Inputs: id (required), timeout_ms, interval_ms.
hcloud_zone_change_primary_nameservers_actionADestructive
hcloud_zone_change_protection_actionCDestructive
Change a Zone's Protection
Changes the protection configuration of a Zone.
Inputs: body (required), id_or_name (required), wait.
hcloud_zone_change_ttl_actionADestructive
Change a Zone's Default TTL
Changes the default Time To Live (TTL) of a Zone.
This TTL is used for RRSets that do not explicitly define a TTL.
Only applicable for Zones in primary mode.
Operation specific errors
Status | Code | Description |
|
| This operation is not supported for this Zone's |
Inputs: body (required), id_or_name (required), wait.
hcloud_zone_import_zonefile_actionADestructive
Import a Zone file
Imports a zone file, replacing all resource record sets (RRSets).
The import will fail if existing RRSet are change protected.
See Zone file import for more details. Only applicable for Zones in primary mode.
Operation specific errors
Status | Code | Description |
|
| This operation is not supported for this Zone's |
Inputs: body (required), id_or_name (required), wait.
hcloud_zone_rrset_add_records_actionA
Add Records to an RRSet
Adds resource records (RRs) to an RRSet in the Zone.
For convenience, the RRSet will be automatically created if it doesn't exist. Otherwise, the new records are appended to the existing RRSet.
Only applicable for Zones in primary mode.
Operation specific errors
Status | Code | Description |
|
| This operation is not supported for this Zone's |
Inputs: body (required), rr_name (required), rr_type (required), id_or_name (required), +1 more.
hcloud_zone_rrset_change_protection_actionADestructive
Change an RRSet's Protection
Changes the protection of an RRSet in the Zone.
Only applicable for Zones in primary mode.
Operation specific errors
Status | Code | Description |
|
| This operation is not supported for this Zone's |
Inputs: body (required), rr_name (required), rr_type (required), id_or_name (required), +1 more.
hcloud_zone_rrset_change_ttl_actionADestructive
Change an RRSet's TTL
Changes the Time To Live (TTL) of an RRSet in the Zone.
Only applicable for Zones in primary mode.
Operation specific errors
Status | Code | Description |
|
| This operation is not supported for this Zone's |
Inputs: body (required), rr_name (required), rr_type (required), id_or_name (required), +1 more.
hcloud_zone_rrset_remove_records_actionADestructive
Remove Records from an RRSet
Removes resource records (RRs) from an existing RRSet in the Zone.
For convenience, the RRSet will be automatically deleted if it doesn't contain any RRs afterwards.
Only applicable for Zones in primary mode.
Operation specific errors
Status | Code | Description |
|
| This operation is not supported for this Zone's |
Inputs: body (required), rr_name (required), rr_type (required), id_or_name (required), +1 more.
hcloud_zone_rrset_set_records_actionADestructive
Set Records of an RRSet
Overwrites the resource records (RRs) of an existing RRSet in the Zone.
Only applicable for Zones in primary mode.
Operation specific errors
Status | Code | Description |
|
| This operation is not supported for this Zone's |
Inputs: body (required), rr_name (required), rr_type (required), id_or_name (required), +1 more.
hcloud_zone_rrset_update_records_actionADestructive
Update Records of an RRSet
Updates resource records' (RRs) comments of an existing RRSet in the Zone.
Only applicable for Zones in primary mode.
Operation specific errors
Status | Code | Description |
|
| This operation is not supported for this Zone's |
Inputs: body (required), rr_name (required), rr_type (required), id_or_name (required), +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 202 tools
Many tools have near-identical or overlapping purposes: parallel hand-tuned/generated pairs (hcloud_get_server vs hcloud_get_server_raw, hcloud_server_change_type vs _action, hcloud_server_rebuild vs _action, hcloud_server_power vs individual power on/off/reboot/shutdown/reset actions). The numerous per-resource action-listing tools (list_*_actions, get_*_actions, get_*_actions_id, get_*_action) are hard to tell apart, forcing misselection.
A hcloud_ prefix is present, but conventions are mixed: some tools are bare get_/list_ while others append _action or _raw; pluralization is inconsistent (e.g. hcloud_get_load_balancers_actions vs hcloud_list_load_balancer_actions) and get_/list_ are used interchangeably for the same concept.
202 tools for one cloud provider API is an extreme mismatch, far exceeding the typical 3-15 range. Much of the surface is redundant per-resource action-listing endpoints and duplicate raw/wrapped variants that bloat the set.
Coverage of the Hetzner Cloud domain is essentially complete: full CRUD for servers, networks, firewalls, load balancers, floating/primary IPs, volumes, certificates, and DNS zones/RRSets, plus actions and a raw escape hatch. Minor gaps are deprecated endpoints and some hand-tuned/generated inconsistency, but core lifecycle operations are all present.
Maintenance
Related MCP Connectors
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server for interacting with the Supabase platform
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that publishes CLI tools on your machine for discoverability by LLMs7 npm1MIT
- AlicenseNot gradedqualityAmaintenanceModel Context Protocol server for full Hetzner Cloud + Storage API automation. Exposes all official Hetzner operations as MCP tools so AI agents can manage servers, networking, load balancers, firewalls, volumes, DNS zones, and storage boxes from one server.1MIT
- AlicenseBqualityBmaintenanceMCP server for the Hetzner Cloud API. Manage servers, networks, volumes, firewalls, load balancers, and more through the Model Context Protocol.185657 npm7Functional Source , Version 1.1, MIT Future
- FlicenseAqualityCmaintenanceMCP server for Personal OS API that enables managing tasks, notes, projects, collections, reviews, and more through typed tools over stdio.66-