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, SHA256SUMS and 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 by tests/tools-contract.test.ts against tests/snapshots/tools-contract.json.

• hcloud_raw_request as 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 carries confirm: "YES".

• Optional operator switches HETZNER_READ_ONLY=true (only read-only tools and GET through hcloud_raw_request run) and HETZNER_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 build

Pin 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:live

Configuration

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.

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-18 or 2025-11-25 gets that revision back; a client that asks for a newer one (for example 2026-07-28) in initialize gets 2025-11-25 (tests/server.test.ts).

• 2026-07-28 is opt-in: with MCP_SERVE_MODERN_PROTOCOL=true the server also answers a client that opens with server/discover and serves it the 2026-07-28 revision, with the same tools. A client that opens with initialize still gets the 2025-era session above (tests/serve-protocol.test.ts). The default is false: a client in auto mode (such as the python mcp client) would switch to the new revision as soon as it is offered, so turn it on only after checking the client. See docs/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 logs mcp transport error on stderr and exits with code 1. Keep large arguments (for example user_data) well below that size. Outbound, a tool result is cut at MAX_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

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/maxLength and flat array elements (element type, items.enum, items.minimum/maximum), plus required. 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 as sort or status it 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 keys confirm, wait and auto_paginate are always tolerated, so sending confirm while HETZNER_CONFIRM_WRITES is disabled, or wait / auto_paginate to 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, %2e in 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, _dmarc and 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 3986 pchar such 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.env

Options: --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:

1. npm run inspector opens the MCP Inspector with this server.

2. tools/list: verify the count equals toolCount in tests/snapshots/tools-contract.json and that every wrapper in the table above appears.

3. hcloud_list_servers (no args): verify against at least one known server in your account.

4. hcloud_get_server with name: "<one of your server names>": should return id, type, ip.

5. hcloud_create_ssh_key with { name: "mcp-smoke", public_key: "<your test key>" }: note the returned id.

6. hcloud_delete_ssh_key with 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.