hetzner-code-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| HOST | No | Listen address. | 0.0.0.0 |
| PORT | No | Listen port. | 3000 |
| HETZNER_API_TOKEN | No | Cloud API token for the default project. For several projects, use HETZNER_API_TOKEN_<PROJECT> instead, where the suffix becomes the lower-cased project name. | |
| HETZNER_READ_ONLY | No | Set to 1 to remove hetzner_execute and block every non-GET request. | off |
| HETZNER_MCP_SECRET | No | Required in hosted mode. At least 32 characters; encrypts stored credentials and signs the browser cookie. | |
| HETZNER_ROBOT_USER | No | Robot webservice user, created in Robot under Settings → Web service and app settings. | |
| HETZNER_MCP_DB_PATH | No | SQLite file path. Put it on a persistent volume. | ./data/hetzner-mcp.sqlite |
| HETZNER_MCP_TENANTS | No | Required in hosted mode if HETZNER_MCP_TENANTS_FILE is not set. Tenant JSON provided inline. | |
| HETZNER_ALLOW_BILLED | No | Set to 1 to allow requests that cost money. | off |
| HETZNER_MCP_ICON_PATH | No | Path to an .svg, .png or .ico file, served as favicon and announced as the MCP server icon. | |
| HETZNER_MCP_PUBLIC_URL | No | Required in hosted mode. Public https base URL; the connector URL is <this>/mcp. | |
| HETZNER_ROBOT_PASSWORD | No | Robot webservice password. | |
| HETZNER_APPROVAL_DIALOG | No | Set to 1 to ask for approval in a client dialog instead of requiring confirmed: true. | off |
| HETZNER_DEFAULT_PROJECT | No | Optional default project name when using project-specific Cloud API tokens. Without it, tools must be given a project. | |
| HETZNER_MAX_OUTPUT_CHARS | No | Longer results are truncated. | 40000 |
| HETZNER_MCP_TENANTS_FILE | No | Required in hosted mode if HETZNER_MCP_TENANTS is not set. Path to the tenant JSON. | |
| HETZNER_MCP_CF_ACCESS_AUD | No | Cloudflare Access application AUD tag for protecting /connect pages. | |
| HETZNER_SKIP_CONFIRMATION | No | Set to 1 to send billed and destructive requests without asking for approval first. | off |
| HETZNER_MAX_REQUESTS_PER_RUN | No | API calls allowed per code run. | 200 |
| HETZNER_MCP_ACCESS_TOKEN_TTL | No | Lifetime in seconds of access tokens issued to MCP clients. | 3600 |
| HETZNER_MCP_REFRESH_TOKEN_TTL | No | Lifetime in seconds of refresh tokens issued to MCP clients (90 days). | 7776000 |
| HETZNER_EXECUTE_TIMEOUT_SECONDS | No | Maximum runtime of one code run. | 120 |
| HETZNER_REQUEST_TIMEOUT_SECONDS | No | Timeout of a single API call. | 30 |
| HETZNER_MCP_CF_ACCESS_TEAM_DOMAIN | No | Cloudflare Access team domain for protecting /connect pages. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Hetzner Cloud API (servers, volumes, networks, firewalls, load balancers, IPs, images, DNS zones, Storage Boxes) and Hetzner Robot API (dedicated servers and their firewall, reset, rescue, rDNS, vSwitch) in code mode. Cloud resources are reached through the hetzner object, dedicated servers through the robot object; a server missing in one may live in the other. Workflow: 1) hetzner_search to find the operation and its parameters, 2) hetzner_query for reads (GET only), 3) hetzner_execute only for changes. Do the filtering and aggregation inside the code and return only what is needed, list responses are large.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| hetzner_searchA | 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 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')) |
| hetzner_queryB | 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 }).
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 })); } |
| hetzner_executeA | 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 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 }).
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 }; } |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.