Skip to main content
Glama

hetzner-code-mcp

MCP server for the Hetzner APIs in code mode: instead of one tool per endpoint, the model looks an operation up in the API reference and then runs a small piece of JavaScript against the API. Three tools cover all 327 operations:

  • Cloud API (222 operations): servers, volumes, networks, firewalls, load balancers, IPs, images, certificates, DNS zones, Storage Boxes

  • Robot API (105 operations): dedicated servers and their firewall, reset, rescue and boot configuration, reverse DNS, failover IPs, vSwitches, SSH keys, server ordering

Tool

Purpose

Can change things

hetzner_search

Explore the API reference (search(), describe(), raw operations). No token needed.

no

hetzner_query

Run JavaScript that reads from the API. Only GET requests pass.

no

hetzner_execute

Run JavaScript that may also POST, PUT and DELETE.

yes

Reads and writes are separate tools, so a client can auto-approve hetzner_query and still ask before every hetzner_execute. Requests that cost money are refused until you switch them on, and both billed and destructive requests wait for an approval that shows the price or the affected resource (details).

Why code mode: one call can chain requests, follow pagination and return only the fields that matter, instead of pushing whole API responses through the model. New Hetzner endpoints arrive with npm run update-spec, without new tool code.

Runs locally over stdio, or hosted as a remote connector for a team.

Not affiliated with Hetzner Online GmbH.

Setup

Requires Node.js 22.13 or newer.

Create an API token in the Hetzner Console under Security → API Tokens. A token belongs to exactly one project. A read-only token is enough for hetzner_query.

Claude Code:

claude mcp add hetzner --scope user \
  --env HETZNER_API_TOKEN=your-token \
  -- npx -y hetzner-code-mcp

Other clients (mcpServers JSON):

{
  "mcpServers": {
    "hetzner": {
      "command": "npx",
      "args": ["-y", "hetzner-code-mcp"],
      "env": { "HETZNER_API_TOKEN": "your-token" }
    }
  }
}

Several projects

Set one variable per project. The part after HETZNER_API_TOKEN_ becomes the project name (lower-cased), which the tools accept as project.

HETZNER_API_TOKEN_PROD=...
HETZNER_API_TOKEN_STAGING=...
HETZNER_DEFAULT_PROJECT=prod   # optional; without it, `project` must be passed

HETZNER_API_TOKEN (no suffix) is the project default and is used when no project is named.

Dedicated servers (Robot)

Robot has its own credentials: a webservice user, created in Robot under Settings → Web service and app settings. It is valid for the whole Robot account and independent of Cloud projects.

HETZNER_ROBOT_USER='#ws+xxxxxxxx'
HETZNER_ROBOT_PASSWORD='...'

Robot has no read-only users: the webservice user can always change, order and cancel. hetzner_query still only lets GET requests through. Robot blocks the calling IP for 10 minutes after three failed logins, so check the credentials before retrying.

Options

Variable

Default

Meaning

HETZNER_READ_ONLY

off

1 removes hetzner_execute and blocks every non-GET request

HETZNER_ALLOW_BILLED

off

1 allows requests that cost money (see guard)

HETZNER_SKIP_CONFIRMATION

off

1 sends billed and destructive requests without asking first

HETZNER_APPROVAL_DIALOG

off

1 asks for approval in a client dialog instead of confirmed: true

HETZNER_EXECUTE_TIMEOUT_SECONDS

120

Maximum runtime of one code run

HETZNER_REQUEST_TIMEOUT_SECONDS

30

Timeout of a single API call

HETZNER_MAX_REQUESTS_PER_RUN

200

API calls allowed per code run

HETZNER_MAX_OUTPUT_CHARS

40000

Longer results are truncated

Related MCP server: Cloudflare MCP

What the code can use

hetzner.request({ method, path, query, body, api })
hetzner.get(path, query)   hetzner.post(path, body)   hetzner.put(path, body)   hetzner.delete(path)
hetzner.paginate(path, query)        // all pages of a list endpoint
hetzner.waitForAction(response)      // waits for an asynchronous action, throws if it failed
sleep(ms)   console.log(...)

robot.get(path, query)   robot.post(path, body)   robot.put(path, body)   robot.delete(path)

hetzner talks to the Cloud API of the selected project, robot to the Robot webservice. Robot bodies are passed as plain objects and sent form-encoded; nested values become rules[input][0][action]=accept. Storage Box paths (/storage_boxes, /storage_box_types) are sent to api.hetzner.com, everything else under hetzner to api.hetzner.cloud.

Example for hetzner_query:

async () => (await hetzner.paginate('/servers'))
  .map(s => ({ name: s.name, status: s.status, type: s.server_type.name, ip: s.public_net.ipv4?.ip }))

Requests are checked before they are sent

Every request is compared with the API reference first: the operation must exist, query and body fields must be known, required fields present, types and enum values valid. A mismatch is reported to the model and nothing is sent:

POST /servers was not sent, it does not match the API reference:
- body: required field "server_type" is missing
- body: unknown field "server_typ" (did you mean "server_type"?). Allowed: name, location, server_type, ...
- See describe('create_server') in hetzner_search for all inputs.

For Robot, which publishes no schemas, the operation and the top-level input names are checked. hetzner.request({ ..., validate: false }) skips the check if the reference is wrong.

Cost and damage guard

hetzner_execute treats two kinds of requests specially.

Billed requests create something Hetzner charges for or raise a price: creating servers, volumes, load balancers, floating and primary IPs, snapshots and Storage Boxes, changing a server, load balancer or Storage Box type, enlarging a volume, enabling backups, and ordering through Robot. They are refused unless HETZNER_ALLOW_BILLED=1 is set (hosted mode: "billed": true on the tenant).

Destructive requests delete something or destroy data: every DELETE, rebuilding a server, disabling backups, rolling back a Storage Box snapshot, importing a zone file, and in Robot cancellations and OS installations. Configuration changes that cost nothing and lose no data, such as firewall rules or DNS records, are not held back.

Both kinds are not sent on the first attempt. The server works out what the request does and, for billed Cloud requests, the price from Hetzner's price list:

POST /servers was NOT sent, it needs the user's approval first. This request creates a
server, billed per hour until it is deleted (also while powered off). Price: server type
cx23 in nbg1: 4.15 EUR/month, 0.0071 EUR/hour (incl. 19% VAT).

There are two ways to approve:

  • Default: the text goes back to the model, which has to tell the user and repeat the call with confirmed: true. That argument is visible in the client's own approval prompt for the tool call. This relies on the model reporting honestly and on you reading the prompt; it is a speed bump, not a lock.

  • HETZNER_APPROVAL_DIALOG=1: the server asks through an MCP elicitation dialog and the person decides (approve, approve everything else in this run, or decline). The model cannot answer it. Switch this on only if your client really shows such dialogs: some announce the capability and then dismiss the dialog unseen, which would decline every guarded request. The billing switch is the hard limit: with it off, no code can create a billable resource. Prices for Robot orders and Storage Boxes are not looked up. HETZNER_SKIP_CONFIRMATION=1 turns the approval step off for automation.

Hosted mode (claude.ai connector for a team)

hetzner-code-mcp --http runs the server as a remote MCP endpoint (Streamable HTTP):

  1. Someone adds the connector in claude.ai (or any OAuth-capable MCP client).

  2. The client opens this server's connect page. It lists the Cloud projects and Robot accounts from your tenant configuration; the person clicks Verbinden on each one they have access to and stores an API token (Cloud) or a webservice user (Robot). The server checks the credentials against Hetzner before storing them.

  3. Fertig – zurück zu Claude completes the client's OAuth flow.

The tools then take project (and robot_account when several Robot accounts are connected). hetzner_list_accounts shows the status and hands out a link to connect more or replace credentials. Credentials are stored AES-GCM encrypted in SQLite; credentials Hetzner rejects later are marked, and the model hands out the link to replace them.

This server is the OAuth authorization server for the MCP client; Hetzner only sees API-token requests. The connect pages are in German.

Tenant configuration

{
  "tenants": [
    { "id": "prod", "name": "Production", "type": "cloud", "writes": false },
    { "id": "staging", "name": "Staging", "type": "cloud", "writes": true, "billed": true },
    { "id": "dedicated", "name": "Dedicated servers", "type": "robot", "writes": false }
  ]
}

Field

Meaning

id

Slug the model passes as project (cloud) or robot_account (robot).

name

Shown on the connect page and to the model.

type

cloud (default): a Cloud project, connected with an API token. robot: a Robot account, connected with a webservice user.

writes

true allows POST/PUT/DELETE for this tenant. Default: only GET requests pass, whatever the stored token could do.

billed

true (with writes) allows requests that cost money. Default: refused. Approval in hosted mode works through confirmed: true.

A Hetzner token does not say which project it belongs to, so the server cannot verify that a token stored under "Production" really is from that project.

Environment

Variable

Default

Purpose

HETZNER_MCP_PUBLIC_URL

—

Required. Public https base URL. The connector URL is <this>/mcp.

HETZNER_MCP_SECRET

—

Required. ≥ 32 characters; encrypts stored credentials and signs the browser cookie. Changing it invalidates all connections.

HETZNER_MCP_TENANTS_FILE / HETZNER_MCP_TENANTS

—

Required. Path to the tenant JSON, or the JSON inline.

HETZNER_MCP_DB_PATH

./data/hetzner-mcp.sqlite

SQLite file. Put it on a persistent volume.

PORT / HOST

3000 / 0.0.0.0

Listen address.

HETZNER_MCP_CF_ACCESS_TEAM_DOMAIN / HETZNER_MCP_CF_ACCESS_AUD

—

Put the connect pages behind Cloudflare Access: team domain and the Access application's AUD tag. /connect/* then requires a valid Access token, checked by the server itself.

HETZNER_MCP_ICON_PATH

—

Path to an .svg, .png or .ico file, served as favicon and announced as the MCP server icon.

HETZNER_MCP_ACCESS_TOKEN_TTL

3600

Lifetime (s) of access tokens issued to MCP clients.

HETZNER_MCP_REFRESH_TOKEN_TTL

7776000

Lifetime (s) of refresh tokens issued to MCP clients (90 days).

The options from the table further up (HETZNER_EXECUTE_TIMEOUT_SECONDS and so on) apply too.

The Dockerfile builds a ready image:

docker build -t hetzner-mcp .
docker run -p 3000:3000 -v hetzner-mcp-data:/data \
  -v $PWD/tenants.json:/config/tenants.json:ro \
  -e HETZNER_MCP_TENANTS_FILE=/config/tenants.json \
  -e HETZNER_MCP_PUBLIC_URL=https://hetzner-mcp.example.com \
  -e HETZNER_MCP_SECRET="$(openssl rand -base64 48)" \
  hetzner-mcp

Run it behind TLS (reverse proxy). Then in claude.ai: Settings → Connectors → Add custom connector with https://hetzner-mcp.example.com/mcp.

Protect the connect pages. Anyone who can open the connector URL can start the OAuth flow and store their own credentials; they never see anyone else's. To keep strangers out altogether, put the path /connect behind Cloudflare Access (or a comparable login) and set the two HETZNER_MCP_CF_ACCESS_* variables. Leave /mcp, /token, /register, /authorize and /.well-known/* outside: claude.ai calls them from its servers.

Security

  • The code runs in its own locked-down process. Each run starts a Node process with the permission model: no file system outside this package, no child processes, no workers, an empty environment. Inside it, the code runs in a V8 context without require, process, fetch, timers or eval.

  • Credentials never enter that process. The code passes request descriptions (method, path, query, body) to the server, which adds the credentials and only talks to the three Hetzner hosts.

  • Runs are bounded: a time limit (the process is killed, also when the code loops forever), 256 MB of memory, and a cap on API calls per run.

  • Writes need the second tool, and can be switched off per installation (HETZNER_READ_ONLY) or per tenant (writes in hosted mode).

  • Billed requests are off by default and, like destructive ones, wait for an approval (guard).

Use read-only tokens where you only want to look: that is enforced by Hetzner, not by this server.

Updating the API reference

spec/operations.json is generated from the official OpenAPI specs (docs.hetzner.cloud/cloud.spec.json and hetzner.spec.json) and, because Robot has no OpenAPI spec, from the HTML documentation at robot.hetzner.com/doc/webservice/en.html.

npm run update-spec

Development

npm install
npm test

The tests start the built server (stdio and --http) and talk to a local fake of the Hetzner APIs. No real API is called.

Releases: bump version in package.json and SERVER_VERSION in src/config.ts, push a tag v<version>. The workflow publishes to npm via Trusted Publishing.

License

MIT

Available Tools

3 tools
hetzner_executeChange resources through the Hetzner APIA
Destructive

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

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

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

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

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

Inputs: code (required), project, confirmed.

hetzner_queryRead from the Hetzner APIB
Read-onlyIdempotent

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

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

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

Inputs: code (required), project.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 3 tools

    Disambiguation5/5

    The three tools map cleanly to discover (hetzner_search), read (hetzner_query), and mutate (hetzner_execute). Although hetzner_execute also permits GET, the descriptions explicitly direct pure reads to hetzner_query, leaving no real ambiguity about which tool to pick.

    Naming Consistency5/5

    All tools use the same hetzner_ prefix followed by a clear action verb (search, query, execute). The pattern is predictable and consistent throughout.

    Tool Count5/5

    Three tools is exactly right for a generic API-wrapper server: one for reference lookup, one for safe reads, one for guarded writes. Each tool has a distinct, essential role and none feels redundant.

    Completeness5/5

    The surface covers the full lifecycle for Hetzner's Cloud, Storage Box, and Robot APIs: discovery via search, reads via query, and all mutations via execute with validation and billing/destructive guards. No obvious operation category is missing.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      F
      maintenance
      Enables AI models to dynamically create and execute their own custom tools through a meta-function architecture, supporting JavaScript, Python, and Shell runtimes with sandboxed security and human approval flows.
      5
      10
      MIT
    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables interaction with the complete Cloudflare API using a codemode pattern that allows agents to search the OpenAPI spec and execute API calls via JavaScript. This approach minimizes token usage by keeping the massive specification on the server and only returning relevant results.
      12 npm
      129
      Apache 2.0