hetzner-mcp

An MCP server that lets Claude operate a Hetzner estate: Cloud servers, DNS (Cloudflare and Hetzner DNS), hosts over SSH, Coolify, and multi-step recipes. Every write is a dry run until confirmed, protected servers refuse destructive calls, and every call is audited.

Status: v0.1.0. Built and tested against mocked APIs, a real SSH host, real Docker and a real Caddy. Not yet pointed at a live Hetzner project.

Modules and tools (53 with everything configured)

hz_capabilities is always present and says which modules are on and what each one needs.

Related MCP server: hetzner-mcp-server

Safety model

• Dry run by default. Write tools return a plan unless called with confirm: true. Delete and rebuild also need confirm_name equal to the server name.

• Protected resources. A server is protected when it is in PROTECTED_SERVERS, has the Hetzner label protected=true, is marked protected in the host registry, or has Hetzner delete/rebuild protection on. Destructive calls on it are refused even with confirm: true.

• Host registry. SSH only reaches hosts listed in config/hosts.json. File reads and writes stay inside each host's allowed_paths. .env files return their keys, never values.

• Audit log. Every call (read, dry run, refused, executed) is appended to data/audit.jsonl with secrets masked.

• Caddy edits are fenced with markers, backed up, validated and rolled back on failure before a reload.

Stack

Node 22, TypeScript (strict), @modelcontextprotocol/sdk, zod, ssh2, Express (Streamable HTTP), Biome, Vitest, pnpm, Docker.

Quickstart (local, stdio)

pnpm install
cp .env.example .env            # fill in what you have
cp config/hosts.example.json config/hosts.json
pnpm build

Claude Desktop / Claude Code config:

{
  "mcpServers": {
    "hetzner": {
      "command": "node",
      "args": ["C:\\path\\to\\hetzner-mcp\\dist\\index.js"],
      "env": { "HCLOUD_TOKEN": "…", "SSH_KEY_PATH": "C:\\Users\\you\\.ssh\\hetzner_mcp_ed25519", "HOSTS_FILE": "C:\\path\\to\\hetzner-mcp\\config\\hosts.json" }
    }
  }
}

Hosted (HTTP, behind Caddy on the app server): see docs/RUNBOOK.md.

CI checks

pnpm typecheck && pnpm lint && pnpm test

CI runs the same three plus pnpm build and a gitleaks secret scan.

Growing it

Add a folder under src/modules/<id>/ exporting a Module (status() + register()), register tools through the ToolKit (t.read / t.write), and list it in src/modules/index.ts. The guard, audit and capability report come for free. See docs/CONTRIBUTING.md.

License

MIT