Hetzner Cloud MCP Server

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

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 root@1.2.3.4

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: labs@wbf.solutions.

Links

- Landing page: hetzner-cloud-mcp.wbf.tools
- Built by: WBF Solutions
- Contact: labs@wbf.solutions

License

MIT — WBF Solutions | labs@wbf.solutions