mcp-hetzner

A Model Context Protocol server that exposes the Hetzner Cloud, Hetzner DNS and Storage Box APIs as MCP tools, so any MCP-aware agent can manage your Hetzner infrastructure conversationally.

• Cloud API — full CRUD for servers, volumes, networks, firewalls, load balancers, floating IPs, primary IPs, SSH keys, images, ISOs, placement groups, TLS certificates, plus server actions (power on/off, reboot, rescue, rebuild, snapshot, resize, …).

• DNS API — full CRUD for zones, records (incl. bulk create/update), primary servers, zone-file import/export and validation.

• Storage Box API — full CRUD for Storage Boxes, sub-accounts, snapshots, snapshot plans, and box/sub-account actions (password reset, access settings, type change, snapshot rollback).

• Transports — both stdio and streamable HTTP are supported.

137 tools in total, registered under three clear namespace prefixes: cloud_*, dns_*, sb_*.

⚠️ Disclaimer: This is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Hetzner Online GmbH. "Hetzner" is a trademark of Hetzner Online GmbH and is used here in a purely descriptive sense.

Install

Python 3.10+ required. Install directly from GitHub.

Option A — pipx from GitHub (recommended for end users)

pipx install git+https://github.com/ginkelsoft-development/mcp-hetzner.git

Pipx installs the package in an isolated environment and adds hetzner-mcp to your $PATH. Upgrade later with:

pipx upgrade hetzner-mcp

To pin a specific tag/branch, append @<ref>:

pipx install "git+https://github.com/ginkelsoft-development/mcp-hetzner.git@main"

Option B — pip in a virtualenv

python -m venv .venv
source .venv/bin/activate
pip install git+https://github.com/ginkelsoft-development/mcp-hetzner.git

Option C — clone for development

git clone https://github.com/ginkelsoft-development/mcp-hetzner.git
cd mcp-hetzner
pip install -e .

Smoke test (no tokens needed)

hetzner-mcp --list-tools | python -c "import json,sys; print(len(json.load(sys.stdin)),'tools')"
# -> 137 tools

Tokens

The three Hetzner APIs each use their own token:

Copy .env.example to .env and fill in whichever you need. You can run the server with only the tokens you have — calls to unconfigured APIs return a structured 401 error instead of crashing.

Use it in an MCP-compatible host

Every MCP-compatible host application accepts the same stdio-server block. Drop the snippet below into the host's MCP-server config and you're done.

The universal config block

{
  "mcpServers": {
    "hetzner": {
      "command": "hetzner-mcp",
      "env": {
        "HCLOUD_TOKEN": "...",
        "HDNS_TOKEN": "...",
        "HETZNER_TOKEN": "..."
      }
    }
  }
}

Where each host stores its config

After saving the config, restart the host application. Most hosts surface a tool/plug icon in the chat interface when the server has connected successfully. You can confirm tool registration with a simple prompt such as:

"Run hetzner_health and tell me which tokens are configured."

Tip: absolute paths if hetzner-mcp isn't on the host's PATH

GUI applications often don't inherit your shell's PATH. If you see a "command not found" error in the host's logs, replace "hetzner-mcp" with the full path returned by which hetzner-mcp. Or use the explicit Python form:

{
  "mcpServers": {
    "hetzner": {
      "command": "/full/path/to/python",
      "args": ["-m", "hetzner_mcp"],
      "env": { "HCLOUD_TOKEN": "...", "HDNS_TOKEN": "...", "HETZNER_TOKEN": "..." }
    }
  }
}

Run as HTTP (remote / shared)

Use this when you want a single shared deployment instead of installing the server on each user's machine — for example to plug it into a web-based AI host that only accepts remote MCP servers via custom connectors.

hetzner-mcp --http --host 0.0.0.0 --port 8765

The streamable-HTTP endpoint is mounted at /mcp. Point an MCP-aware client at http://your-host:8765/mcp.

🔒 Don't expose this endpoint to the public internet without a reverse proxy that enforces authentication and TLS. The MCP server itself has no auth layer — anyone who can reach the port can use your tokens.

A minimal hardening checklist before going public:

1. Put the server behind a reverse proxy (Caddy, nginx, Traefik) with TLS.

2. Require authentication at the proxy level (Basic auth, OAuth proxy, Cloudflare Access, Tailscale serve, etc.).

3. Allow-list the IP ranges your host actually calls from, where possible.

4. Use Hetzner API tokens scoped to read-only or to a specific project.

Tool naming

Tools are prefixed by API so it's always obvious which surface they touch:

• cloud_* — Hetzner Cloud (servers, volumes, networks, …) — 91 tools

• dns_* — Hetzner DNS (zones, records, …) — 20 tools

• sb_* — Storage Box (storage boxes, sub-accounts, snapshots, …) — 25 tools

• hetzner_health — reports which tokens are configured (no network call)

Run hetzner-mcp --list-tools for the full list with one-line descriptions.

Quick examples

"Spin up a cx22 in fsn1 with my SSH key, then add an A record for staging.example.com pointing at it."

Calls: cloud_list_ssh_keys → cloud_create_server → dns_list_zones → dns_create_record.

"Show me everything that's running, grouped by location."

Calls: cloud_list_servers, cloud_list_volumes, cloud_list_load_balancers, sb_list_storage_boxes.

"Resize storage-box 12345 from bx11 to bx21 — take a snapshot first."

Calls: sb_create_snapshot → sb_change_storage_box_type.

Safety notes

This server is fully read/write by default. Destructive tools (cloud_delete_server, sb_delete_storage_box, dns_delete_zone, …) will happily wipe resources if asked. For a safer setup, provision tokens with the narrowest permission scope the API supports (Cloud and DNS tokens both support read-only scopes).

Branch model

• main — stable, what's published as releases.

• develop — active development; PRs target this branch.

See CONTRIBUTING.md for the full workflow.

Development

pip install -e ".[dev]"
ruff check src
hetzner-mcp --list-tools

License

MIT — © 2026 Ginkelsoft Development.