Hetzner

Hetzner Cloud MCP 使用指南

透過 @jurislm/hetzner-mcp MCP 工具管理 Hetzner Cloud 基礎設施。

MCP 工具概覽

伺服器管理（9 個工具）

SSH 金鑰管理（4 個工具）

Volume 管理（4 個工具）

⚠️ 這 4 個工具只操作 Hetzner API 層的 attach/detach。不處理 Linux 端的 mount／/etc/fstab——見下方「常見陷阱：Reboot 後 Volume 不會自動 mount」，attach 後仍需手動 SSH 進去寫 fstab。

Storage Box 管理（22 個工具）

參考資料（3 個工具）

常見工作流程

建立新伺服器

在建立伺服器前，先取得有效的參數值：

1. hetzner_list_server_types  → 選擇 server_type（如 "cx22"、"cax31"）
2. hetzner_list_images        → 選擇 image（如 "ubuntu-24.04"）
3. hetzner_list_locations     → 選擇 location（如 "nbg1"、"fsn1"）
4. hetzner_list_ssh_keys      → 取得 SSH 金鑰名稱或 ID
5. hetzner_create_server      → 使用上述參數建立

hetzner_create_server 完整參數：

• name（必填）— 伺服器名稱
• server_type（必填）— 規格代號（e.g. "cx22"）
• image（必填）— OS 映像（e.g. "ubuntu-24.04"）
• location（選填）— 資料中心（e.g. "nbg1"）
• ssh_keys（選填）— SSH 金鑰名稱或 ID 陣列
• labels（選填）— 標籤 key-value object（e.g. {"env": "production"}）
• start_after_create（選填，預設 true）— 建立後立即啟動

篩選伺服器

hetzner_list_servers 支援 label_selector 過濾：

label_selector: "env=production"

管理 SSH 金鑰

新增金鑰時 public_key 需填入公鑰內容字串（非路徑）：

name: "my-macbook"
public_key: "ssh-ed25519 AAAA... user@host"

Storage Box：中繼資料用 MCP，實際傳檔用 SSH/SFTP

Storage Box 的管理面（容量查詢、快照、子帳號、保護設定）已有完整 MCP 工具（見上方「Storage Box 管理」）。但實際上傳/下載檔案（rsync、borg 備份）MCP 不支援，仍需直接 SSH/SFTP：

# ~/.ssh/config 建議設定（port 23 = SFTP/rsync/borg 可用）
Host storagebox
  HostName u<id>.your-storagebox.de
  User u<id>
  Port 23
  IdentityFile ~/.ssh/cx53-storagebox

# 連線確認
ssh storagebox

# 上傳備份
rsync -avz -e "ssh -p 23" ./backup/ storagebox:backups/

⚠️ port 22 vs 23 關鍵差異：

• Port 22：一般 shell 存取，只支援 create 時注入的 SSH key
• Port 23：SFTP / SCP / rsync / borg，支援後加的 ~/.ssh/authorized_keys key
• 備份工具（rsync、borg）必須用 port 23；後加的 key 在 port 22 無效

備份前空間預檢查

備份 pipeline（cron job、add-judgment-backup-sync 等）在執行實際傳檔前，應先用 MCP 工具確認空間足夠，避免傳到一半才發現滿了：呼叫 hetzner_assert_storage_box_space(id=561406, required_gib=20, response_format="json")。

• 空間足夠 → 正常回傳，ok: true
• 空間不足 → isError: true，pipeline 應中止並警示，不要繼續執行 rsync/pg_dump
• 只想看目前用量、不做斷言 → 用 hetzner_get_storage_box_stats(id=561406)

兩個工具回傳的完整欄位（response_format: "json" 時）：

hetzner_assert_storage_box_space 另外多回傳 ok（boolean）與 required_gib（回傳原始請求值）。

不支援的功能

此 MCP 伺服器不支援（需用 Hetzner Cloud Console UI、hcloud CLI 或 SSH/SFTP）：

• Storage Box 實際檔案傳輸（rsync、borg、SFTP 上傳/下載）— 用 SSH/SFTP 直接操作（見上方）
• Firewalls（防火牆）管理
• Projects（專案）管理 — 一個 API token 只能存取單一 project
• Load Balancers / Floating IPs / Private Networks
• 帳單相關操作

常見陷阱

Reboot 後 Volume 不會自動 mount

Hetzner Volume attach 不寫 fstab。Reboot 後 /dev/sdb 沒 mount，所有依賴該 mount path 的 container 啟動失敗（Exit 127）。

預防（建立 server 後立刻做）：

ssh root@<ip>
UUID=$(blkid -s UUID -o value /dev/sdb)
echo "UUID=$UUID /mnt/HC_Volume_<id> ext4 discard,nofail,defaults 0 0" >> /etc/fstab
mount -a   # 測試 fstab 語法

• nofail 關鍵 — Volume 異常時不阻塞 boot
• discard 啟用 TRIM 給 SSD

開機後 IP 變了

Hetzner 預設配 IPv4 + IPv6。hetzner_get_server 回傳 IPv4 public_net.ipv4.ip 是穩定的（除非主動 reassign）。但若用 floating IP，重啟可能切換，要看實際 attach 狀態。

Server name 不可用做識別

API 操作要用 id（數字），不是 name。name 只是 label。

參考資料

• 規格與定價對照：references/server-types.md
• 資料中心位置選擇：references/locations.md

注意事項

⚠️ 危險操作

• hetzner_delete_server：不可逆，會永久刪除伺服器與資料
• hetzner_power_off_server：硬關機（等同拔電源），可能造成資料損毀，執行前確認用戶同意
• hetzner_create_server：立即建立計費資源，確認規格與數量

API Token 權限

• 列出/查詢操作：Read 權限即可
• 建立/刪除操作：需要 Read & Write 權限
• 一個 token 只能存取單一 Hetzner Cloud 專案

response_format

• 所有查詢工具支援 response_format: "markdown" | "json"（預設 "markdown"）
• 刪除工具（delete_server、delete_ssh_key）無此參數

環境變數設定

# ~/.zshenv
export HETZNER_API_TOKEN="your_token_here"

取得 Token：Hetzner Cloud Console → 專案 → Security → API Tokens

外部連結

• Hetzner Cloud 官方文件
• jurislm/hetzner-mcp GitHub