Hetzner Cloud MCP Server

The only Hetzner MCP with SSH server management. API + SSH in one tool.

PHP 8.1+ License: MIT MCP Protocol

Manage your Hetzner Cloud infrastructure from Claude.ai, Claude Desktop, VS Code, Cursor, or any MCP-compatible client. The best part is that you can control and build anything into your servers using your phone with Claude, ChatGPT, or any other AI chat app. Two management layers give you complete control:

• Layer 1 — Hetzner Cloud API: Server power, metrics, snapshots, backups, firewalls, DNS zones and records, rescue mode, server rebuild and rescale. Works even when the server OS is unresponsive.
• Layer 2 — SSH: Services, logs, Nginx, MySQL, supervisor, cron, UFW, disk/memory/CPU monitoring. Real sysadmin tools, not just API wrappers.

60 tools. Dynamic multi-server configuration. Self-hosted and open source.

---

Why This MCP?

Every existing Hetzner MCP only wraps the Cloud API. This one adds a full SSH management layer — the tools you actually need when managing production servers. Two layers, 60 tools, self-hosted.

Feature	Included
Cloud API (server power, metrics, snapshots, backups, firewalls, rescue, rebuild)	Yes
SSH Management (services, logs, Nginx, MySQL, system health)	Yes
DNS Management (zones, records, CRUD)	Yes
Multi-Server (1 to N servers from a single instance)	Yes
Destructive Guards (confirm required for dangerous ops)	Yes
Transport	SSE + Streamable HTTP
Language	PHP 8.1+

---

Quick Start

Prerequisites

• PHP 8.1+ with curl extension
• Composer
• A Hetzner Cloud API token (Console > Security > API Tokens)
• An SSH key for server access (Layer 2 tools)

1. Clone and install

git clone https://github.com/wbf-solutions/hetzner-cloud-mcp.git
cd hetzner-cloud-mcp
composer install

2. Configure

cp .env.example .env

Edit .env with your details:

HETZNER_API_TOKEN=your-cloud-api-token

SERVERS=web
SERVER_WEB_ID=12345678
SERVER_WEB_IP=1.2.3.4
SERVER_WEB_SSH_USER=root

SSH_KEY_PATH=/root/.ssh/id_ed25519

MCP_API_KEY=your-random-key    # generate with: openssl rand -hex 32

3. Set up the SSH key

ssh-keygen -t ed25519 -f /root/.ssh/id_ed25519 -N ""
ssh-copy-id -i /root/.ssh/id_ed25519.pub [email protected]

4. Configure Nginx

server {
    listen 443 ssl;
    server_name mcp.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/mcp.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.yourdomain.com/privkey.pem;

    root /var/www/hetzner-cloud-mcp;
    index api.php;

    location / {
        try_files $uri /api.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_buffering off;
        fastcgi_read_timeout 600;
    }
}

5. Connect to Claude.ai

Settings > Connectors > Add custom connector:

• Name: Hetzner Cloud MCP
• URL: https://mcp.yourdomain.com/api.php

If you set MCP_API_KEY, pass it via the URL: ?mcp=sse&key=YOUR_MCP_API_KEY or configure the API key in the connector's Advanced Settings as a Bearer token.

---

Available Tools (60)

Layer 1 — Hetzner Cloud API (25 tools)

Tool	Description	Destructive
server_info	Server details: status, IP, type, datacenter
server_metrics	CPU, disk, or network metrics
server_power_on	Power on
server_power_off	Hard power off	Confirm
server_shutdown	Graceful ACPI shutdown
server_reboot	Soft reboot
server_reset	Hard reset	Confirm
server_reset_password	Reset root password	Confirm
server_rescue_enable	Enable rescue mode
server_rescue_disable	Disable rescue mode
server_rebuild	Rebuild from image (wipes data)	Confirm
server_change_type	Rescale server plan	Confirm
snapshot_create	Create snapshot
snapshot_list	List snapshots
snapshot_delete	Delete snapshot	Confirm
backup_enable	Enable backups (+20% cost)
backup_disable	Disable backups	Confirm
firewall_list	List firewalls
firewall_get	Get firewall rules
firewall_set_rules	Replace all firewall rules	Confirm
firewall_apply_to_server	Apply firewall to server
firewall_remove_from_server	Remove firewall from server
project_servers_list	List all servers
ssh_keys_list	List SSH keys
action_status	Check async action status

DNS (8 tools, requires HETZNER_DNS_TOKEN)

Tool	Description	Destructive
dns_zones_list	List DNS zones
dns_zone_get	Get zone details
dns_zone_create	Create DNS zone
dns_zone_delete	Delete DNS zone	Confirm
dns_records_list	List records in zone
dns_record_add	Add DNS record
dns_record_update	Update DNS record
dns_record_delete	Delete DNS record	Confirm

Layer 2 — SSH (27 tools)

Tool	Description
ssh_service_status	Check systemd service status
ssh_service_start	Start a service
ssh_service_stop	Stop a service
ssh_service_restart	Restart a service
ssh_services_list	List running services
ssh_disk_usage	Disk space (df -h)
ssh_memory_usage	RAM usage (free -h)
ssh_cpu_load	CPU load + top processes
ssh_process_list	Top processes by mem/CPU
ssh_uptime	Server uptime
ssh_nginx_test	Test Nginx config syntax
ssh_nginx_reload	Reload Nginx (tests first)
ssh_nginx_sites_list	List enabled sites
ssh_nginx_site_config	View site Nginx config
ssh_logs_nginx_error	Tail Nginx error log
ssh_logs_nginx_access	Tail Nginx access log
ssh_logs_syslog	Tail system log
ssh_logs_journal	View systemd journal
ssh_logs_supervisor	View supervisor logs
ssh_mysql_databases	List MySQL databases
ssh_mysql_processlist	Show MySQL processes
ssh_mysql_query	Read-only SQL query
ssh_cron_list	List crontab entries
ssh_supervisor_status	Supervisor program statuses
ssh_supervisor_restart	Restart supervisor program
ssh_ufw_status	Check UFW firewall
ssh_exec	Run command (dangerous cmds blocked)

---

Authentication

Choose the mode that fits your deployment:

Mode	Config	Best for
No auth	MCP_API_KEY= (empty), no OAUTH_*	Behind VPN/firewall, local dev
API key	MCP_API_KEY=your-key	Self-hosted, single user/team
API key + OAuth	Set MCP_API_KEY + OAUTH_* vars	Multi-user, Connectors Directory

API Key (recommended for self-hosting)

Generate a key and set it in .env:

openssl rand -hex 32

Clients pass the key as ?key=XXX or Authorization: Bearer XXX.

OAuth 2.1 (optional)

For advanced deployments or Anthropic Connectors Directory submission, you can add OAuth 2.1 token introspection alongside the static API key. This requires an external OAuth authorization server with an introspection endpoint (RFC 7662). See .env.example for the OAUTH_* variables.

---

Security

• Authentication: API key via query param or Authorization: Bearer header. Optional OAuth 2.1 introspection. Timing-safe validation.
• Destructive guards: All dangerous operations require confirm=true.
• Tool annotations: All tools include readOnlyHint and destructiveHint per MCP spec.
• SSH safety: 29 blocked command patterns (rm -rf, dd, mkfs, curl|sh, passwd, fdisk, etc.).
• Read-only SQL: Only SELECT, SHOW, DESCRIBE, EXPLAIN allowed.
• Rate limiting: Per-IP with atomic flock().

---

Configuration

Define any number of servers in .env:

SERVERS=web,staging
SERVER_WEB_ID=12345678
SERVER_WEB_IP=1.2.3.4
SERVER_WEB_SSH_USER=root
SERVER_WEB_ALIASES=production,prod
SERVER_STAGING_ID=87654321
SERVER_STAGING_IP=5.6.7.8
DEFAULT_SERVER=web

SSH and DNS are optional — tools are auto-disabled when not configured.

See .env.example for the full reference.

---

Client Configuration

Client	Connection
Claude.ai	Settings > Connectors > Add custom connector with SSE URL
Claude Desktop	Add to claude_desktop_config.json
Claude Code	claude mcp add --transport http hetzner URL --header "Authorization: Bearer KEY"
VS Code / Cursor	VS Code extension — coming soon

---

Deployment

Works with VitoDeploy or manual Nginx + PHP-FPM setup. Requires fastcgi_buffering off for SSE streaming. See the full deployment guide in the Quick Start section.

---

Contributing

See CONTRIBUTING.md. Security vulnerabilities: [email protected].

Links

• Landing page: hetzner-cloud-mcp.wbf.tools
• Built by: WBF Solutions
• Contact: [email protected]

License

MIT — WBF Solutions | [email protected]