Skip to main content
Glama

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)

Module

Switched on by

Tools

fleet

always

hz_fleet_overview, hz_host_list, hz_host_register, hz_host_remove

cloud

HCLOUD_TOKEN

hz_server_list, hz_server_get, hz_catalog, hz_action_status, hz_resource_list, hz_server_create, hz_server_power, hz_server_rebuild, hz_server_delete, hz_server_resize, hz_snapshot_create, hz_snapshot_delete, hz_backup_set, hz_firewall_create, hz_firewall_rules_set, hz_firewall_attach, hz_volume_create, hz_volume_action, hz_network_create, hz_network_attach, hz_ip_set_ptr, hz_floating_ip_assign, hz_ssh_key_add

dns

CLOUDFLARE_API_TOKEN and/or HCLOUD_TOKEN

dns_zone_list, dns_records_list, dns_record_set, dns_record_delete, dns_check

host

SSH_KEY or SSH_KEY_PATH

host_status, host_docker_ps, host_logs, host_file_read, host_caddy_routes, host_file_write, host_compose_action, host_caddy_route, host_run, host_bootstrap

coolify

COOLIFY_BASE_URL + COOLIFY_API_TOKEN

coolify_list, coolify_get, coolify_deployments, coolify_env_list, coolify_deploy, coolify_app_action, coolify_env_set

recipes

SSH key (+ HCLOUD_TOKEN for new servers)

recipe_new_app_server, recipe_deploy_stack

audit

always

audit_log

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

Available Tools

6 tools
audit_logAudit logB
Read-onlyIdempotent

Most recent calls through this MCP, newest first: tool, mode (read/dry_run/execute/refused), result, summary.

Inputs: mode, tool, limit, errors_only.

hz_capabilitiesCapabilitiesB
Read-onlyIdempotent

Which modules are on, what they point at, and what to configure to switch the others on.

Inputs: no named parameters.

hz_fleet_overviewFleet overviewA
Read-onlyIdempotent

Every server in every configured Hetzner project: status, type, location, IP, backups, volumes, gross €/month, registry name and role, protection. Volume and traffic costs are not included in the total.

Inputs: no named parameters.

hz_host_listList registered hostsC
Read-onlyIdempotent

The host registry: SSH targets, roles, protection, allowed paths, Caddy.

Inputs: no named parameters.

hz_host_registerRegister or update hostA

Add a host to the registry (or replace its entry). Only registered hosts are reachable over SSH. Set protected=true on the mail server. test_ssh checks the login before saving.

Safety: dry run unless confirm=true.

Inputs: name (required), address (required), port, role, +11 more.

hz_host_removeRemove host from registryA
Destructive

Remove a host entry. The server itself is untouched; SSH tools can no longer reach it.

Safety: dry run unless confirm=true; refused on protected resources.

Inputs: name (required), confirm.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 6 tools

    Disambiguation4/5

    Each tool has a distinct job: registry listing, registration, removal, fleet inventory, audit history, and capability reporting. The only mild overlap is hz_host_list vs hz_fleet_overview (registry SSH targets vs Hetzner cloud servers with costs), but descriptions make the distinction clear enough.

    Naming Consistency4/5

    Most tools follow a hz_<resource>_<action> snake_case pattern (hz_host_list, hz_host_register, hz_host_remove, hz_fleet_overview), which is predictable. Deviations are minor: audit_log lacks the hz_ prefix and hz_capabilities is resource-only with no verb.

    Tool Count5/5

    Six tools is well-scoped for a registry-plus-inventory server; each earns its place (three host CRUD operations, one fleet read, plus two meta/observability tools). Nothing feels redundant or padded.

    Completeness3/5

    Registry lifecycle is covered (list/register/replace/remove), but there is no get-single-host detail tool and no Hetzner server lifecycle operations (create, delete, power, resize, snapshots) despite the server's name implying cloud management. hz_capabilities hints modules may be toggled on, so the surface is intentionally partial but has notable gaps.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers