hetzner-code-mcp
Integrates with the Hetzner Cloud API (servers, volumes, networks, firewalls, load balancers, IPs, images, certificates, DNS zones, Storage Boxes) and the Hetzner Robot API (dedicated servers with firewall, reset, rescue and boot configuration, reverse DNS, failover IPs, vSwitches, SSH keys, server ordering). Enables searching the API reference and running JavaScript to read from or modify resources, with cost and destructive-action guards for billed or destructive operations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hetzner-code-mcp list my Hetzner Cloud servers with their IPs and status"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Explore the API reference ( | no |
| Run JavaScript that reads from the API. Only GET requests pass. | no |
| 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-mcpOther 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 passedHETZNER_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 |
| off |
|
| off |
|
| off |
|
| off |
|
| 120 | Maximum runtime of one code run |
| 30 | Timeout of a single API call |
| 200 | API calls allowed per code run |
| 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=1turns 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):
Someone adds the connector in claude.ai (or any OAuth-capable MCP client).
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.
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 |
| Slug the model passes as |
| Shown on the connect page and to the model. |
|
|
|
|
|
|
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 |
| — | Required. Public https base URL. The connector URL is |
| — | Required. ≥ 32 characters; encrypts stored credentials and signs the browser cookie. Changing it invalidates all connections. |
| — | Required. Path to the tenant JSON, or the JSON inline. |
|
| SQLite file. Put it on a persistent volume. |
|
| Listen address. |
| — | Put the connect pages behind Cloudflare Access: team domain and the Access application's AUD tag. |
| — | Path to an |
|
| Lifetime (s) of access tokens issued to MCP clients. |
|
| 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-mcpRun 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 oreval.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 (writesin 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-specDevelopment
npm install
npm testThe 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
Available Tools
3 toolshetzner_executeChange resources through the Hetzner APIADestructive
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 APIBRead-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.
hetzner_searchSearch the Hetzner API referenceARead-onlyIdempotent
Explore the Hetzner API reference (Cloud API incl. DNS zones, Storage Box API, and the Robot API for dedicated servers) by running JavaScript against it. Makes no API calls and needs no token. Use it before hetzner_query / hetzner_execute to find the right path, parameters and request body.
Globals available in the code:
search(text) -> [{ operationId, method, path, summary, api }] where every word matches id, path, summary or tag.
api is "cloud" | "hetzner" (both called via hetzner) or "robot" (called via robot)
describe(ref) -> one operation, condensed: description, parameters, requestBody, response ("name*" = required).
ref is an operationId or "METHOD /path". Robot operations have no JSON schema; their
description lists Input, Output, Errors and the request limit, plus curl/JSON examples
operations -> all operations with full JSON schemas: { api, operationId, method, path, summary, description,
tags, deprecated, parameters, requestBody, response }
apis -> { cloud, hetzner, robot }, each { baseUrl, overview, tags: [{ name, description }] }. overview is the
general documentation in Markdown (pagination, label selectors, sorting, rate limits, errors)
Examples: async () => search('firewall') async () => describe('create_server') async () => describe('POST /servers/{id}/actions/rebuild') async () => search('robot firewall') async () => describe('robot_post_firewall_server_id') async () => operations.filter(o => o.tags.includes('Zone RRSets')).map(o => o.method + ' ' + o.path) async () => apis.cloud.overview.split('\n## ').find(s => s.startsWith('Label Selector'))
Inputs: code (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
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.
All tools use the same hetzner_ prefix followed by a clear action verb (search, query, execute). The pattern is predictable and consistent throughout.
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.
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
Related MCP Connectors
Email inboxes, webhook URLs, mock APIs and 170+ tools for coding agents over one MCP connection.
Read-only HopBase AI gateway tools: models, limits, docs search, balance and usage for your API key.
AI-callable tools for API mocking, testing, monitoring, security, and automation.
Email inboxes, webhooks, mock APIs, 2FA codes, approvals and 170 tools for AI agents.
Related MCP Servers
- AlicenseAqualityFmaintenanceEnables 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.510MIT
- AlicenseNot gradedqualityFmaintenanceEnables 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 npm129Apache 2.0
- AlicenseBqualityDmaintenanceEnables conversational management of Hetzner Cloud, DNS, and Storage Box infrastructure through 137 MCP tools for CRUD operations and actions like server power control, DNS zone management, and storage box snapshots.100MIT
- AlicenseNot gradedqualityDmaintenanceEnables LLMs to manage and monitor Hetzner Cloud infrastructure, including servers, firewalls, networks, and snapshots, while keeping the API token local and secure.MIT