Skip to main content
Glama
README.md
# 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](#cost-and-damage-guard)).

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](#hosted-mode-claudeai-connector-for-a-team) 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](https://console.hetzner.com/) under
Security → API Tokens. A token belongs to exactly one project. A read-only token is enough
for `hetzner_query`.

Claude Code:

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

Other clients (`mcpServers` JSON):

```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`.

```bash
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](https://robot.hetzner.com/) under Settings → Web service and app settings. It is
valid for the whole Robot account and independent of Cloud projects.

```bash
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](#cost-and-damage-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 |

## What the code can use

```js
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`:

```js
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

```json
{
  "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:

```bash
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](https://nodejs.org/api/permissions.html): 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](#cost-and-damage-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`.

```bash
npm run update-spec
```

## Development

```bash
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](LICENSE)

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