@aiwerk/mcp-server-hetzner

Full-surface Hetzner Cloud MCP server — 189 tools covering the entire Hetzner Cloud + DNS API. BYOK, DRY_RUN and READ_ONLY safety layers.

Install

npx -y @aiwerk/mcp-server-hetzner

Configure

Add to your MCP client config (e.g. Claude Desktop config.json):

{
  "mcpServers": {
    "hetzner": {
      "command": "npx",
      "args": ["-y", "@aiwerk/mcp-server-hetzner"],
      "env": {
        "HCLOUD_TOKEN": "<your-api-token>"
      }
    }
  }
}

Environment variables

| Variable | Required | Default | Description | |---|---|---|---| | HCLOUD_TOKEN | Yes | — | Hetzner Cloud API token (Bearer). Create at Hetzner Console → Project → Security → API Tokens. | | HETZNER_API_TIMEOUT_MS | No | 30000 | Request timeout in milliseconds. | | DRY_RUN | No | 0 | Set to 1 to intercept all write operations without touching the API. Logs the would-be request to stderr. Useful for agent debugging. | | READ_ONLY | No | 0 | Set to 1 to refuse all write operations entirely. Takes precedence over DRY_RUN. Useful for ops safety. |

Auth

Create an API token at Hetzner Console → Your Project → Security → API Tokens.

• Read-only token: safe for listing resources, no billing risk.
• Read-write token: required for creating/modifying/deleting resources. Note that writes to Servers, Volumes, Load Balancers, Floating IPs, and Primary IPs incur Hetzner billing.

Safety layers

Two independent safety layers protect against accidental writes:

| Mode | Behavior on writes | |---|---| | DRY_RUN=1 | Logs the would-be request to stderr, returns { dry_run: true, would_send: { method, path, body, query } }. Read operations pass through normally. | | READ_ONLY=1 | Refuses all write operations with a clear error. Takes precedence over DRY_RUN. Read operations pass through normally. |

When both are set, READ_ONLY wins.

What we guarantee (testable)

These promises are backed by tests that fail if the safety code is removed.

• DRY_RUN=1 blocks all write network calls. Test: tests/safety/dry-run-no-network.test.ts
• READ_ONLY=1 refuses all write tools and never touches the network. Test: tests/safety/read-only-no-network.test.ts
• READ_ONLY takes precedence over DRY_RUN when both are set. Test: tests/safety/read-only-wins.test.ts
• DRY_RUN=1 does not block GET (read) operations. Test: tests/safety/dry-run-get-passthrough.test.ts
• READ_ONLY=1 does not block GET (read) operations. Test: tests/safety/read-only-get-passthrough.test.ts
• HCLOUD_TOKEN is scrubbed from all error messages and error bodies. Test: tests/safety/token-redaction.test.ts
• No auto-retry on 401, 403, 5xx in v0.1.0. Test: tests/safety/no-retry-on-auth-fail.test.ts

Tools (189)

Tools cover the full vendor surface across 31 tag groups:

| Tag group | Count | |---|---| | Server Actions | 27 | | Load Balancer Actions | 17 | | Network Actions | 10 | | Floating IP Actions | 8 | | Primary IP Actions | 8 | | Volume Actions | 8 | | Zone Actions | 8 | | Firewall Actions | 7 | | Load Balancers | 6 | | Servers | 6 | | Zones | 6 | | Zone RRSet Actions | 6 | | Certificates | 5 | | Certificate Actions | 5 | | Firewalls | 5 | | Floating IPs | 5 | | Image Actions | 5 | | Networks | 5 | | Placement Groups | 5 | | Primary IPs | 5 | | SSH Keys | 5 | | Volumes | 5 | | Zone RRSets | 5 | | Images | 4 | | Actions | 2 | | Data Centers | 2 | | ISOs | 2 | | Load Balancer Types | 2 | | Locations | 2 | | Server Types | 2 | | Pricing | 1 |

Key tools

| Tool | Description | |---|---| | list_servers | List all servers (paginated). | | get_server | Get a single server by ID. | | create_server | Create a new server. Billing starts immediately. | | delete_server | Delete a server. Irreversible. | | poweron_server / poweroff_server | Power operations. | | create_server_image | Create a snapshot of a server. | | list_locations | List available locations (cheapest read-only call, safe for smoke tests). | | list_volumes | List block volumes. | | list_load_balancers | List load balancers. | | list_firewalls | List firewalls. | | set_firewall_rules | Replaces ALL existing rules. Read current state first via get_firewall. | | list_zones | List DNS zones. | | list_zone_rrsets | List DNS record sets in a zone. |

Pagination

All list_* tools accept page (default 1) and per_page (default 25, max 50). Check meta.pagination.last_page and meta.pagination.total_entries in the response to determine if more pages exist.

Plural vs singular action tools

Hetzner distinguishes per-resource and project-wide action endpoints by pluralizing the resource noun:

• list_server_actions(server_id) — actions for ONE specific server
• list_servers_actions() — all server actions across the project

Same pattern applies to: certificates, firewalls, floating_ips, images, load_balancers, networks, primary_ips, volumes, zones.

Development

# Install
npm install

# Generate tools from OpenAPI spec
npm run generate

# Build
npm run build

# Test (all 243 tests including 13 safety-claim tests)
npm test

# Smoke test
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | HCLOUD_TOKEN=<token> node dist/src/server.js
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"create_server","arguments":{"name":"test","server_type":"cx22","image":"ubuntu-24.04","location":"fsn1"}}}' | HCLOUD_TOKEN=<token> DRY_RUN=1 node dist/src/server.js

License

MIT — AIWerk