Hetzner Cloud MCP Server

Servidor MCP para a API Hetzner Cloud — gerencie servidores, redes, volumes, firewalls, balanceadores de carga e muito mais. 104 ferramentas em 13 domínios de recursos.

GitHub

Documentação

hetzner-mcp-server

Servidor MCP para a Hetzner Cloud API. Gerencie servidores, redes, volumes, firewalls, balanceadores de carga e muito mais através do Model Context Protocol.

185 ferramentas em 15 domínios de recursos, com 9 pontos de entrada para que você possa escolher o servidor certo para o limite de ferramentas do seu cliente MCP. Um Resource de referência da API somente leitura (reference://hetzner/api) também é exposto em cada ponto de entrada.

Instalação

npm install -g @lazyants/hetzner-mcp-server

Ou execute diretamente:

npx @lazyants/hetzner-mcp-server

Configuração

Defina seu token da API Hetzner Cloud:

export HETZNER_API_TOKEN=your-token-here

Obtenha um token no Hetzner Cloud Console em Security > API Tokens.

As ferramentas de Storage Box usam um host separado (https://api.hetzner.com/v1). Elas usam HETZNER_STORAGE_API_TOKEN se definido, caso contrário, recorrem a HETZNER_API_TOKEN, para que um único token continue funcionando. Defina HETZNER_STORAGE_API_TOKEN somente se você limitar o acesso ao Storage Box a um token dedicado:

export HETZNER_STORAGE_API_TOKEN=your-storage-token-here  # optional

Pontos de Entrada

Comando	Domínios	Ferramentas
`hetzner-mcp-server`	Todos os 15 domínios	185
`hetzner-mcp-servers`	Servidores, Locais/Tipos de Servidor, Preços	33
`hetzner-mcp-networking`	Redes, Firewalls	23
`hetzner-mcp-load-balancers`	Balanceadores de Carga, Certificados	29
`hetzner-mcp-ips`	IPs Flutuantes, IPs Primários	21
`hetzner-mcp-storage`	Volumes, Imagens	18
`hetzner-mcp-storage-boxes`	Storage Boxes (+ snapshots, subcontas, tipos)	30
`hetzner-mcp-config`	Chaves SSH, ISOs, Grupos de Posicionamento	15
`hetzner-mcp-dns`	Zonas DNS	23

Cada ponto de entrada inclui hetzner_wait_for_action; o servidor completo o registra uma vez.

Use servidores divididos para reduzir o tamanho do contexto — escolha apenas as divisões que você precisa.

Claude Code

Adicione ao ~/.claude/settings.json:

{
  "mcpServers": {
    "hetzner": {
      "command": "npx",
      "args": ["-y", "@lazyants/hetzner-mcp-server"],
      "env": {
        "HETZNER_API_TOKEN": "your-token-here"
      }
    }
  }
}

Ou use servidores divididos (escolha as divisões que você precisa):

{
  "mcpServers": {
    "hetzner-servers": {
      "command": "npx",
      "args": ["-y", "-p", "@lazyants/hetzner-mcp-server", "hetzner-mcp-servers"],
      "env": { "HETZNER_API_TOKEN": "your-token-here" }
    },
    "hetzner-networking": {
      "command": "npx",
      "args": ["-y", "-p", "@lazyants/hetzner-mcp-server", "hetzner-mcp-networking"],
      "env": { "HETZNER_API_TOKEN": "your-token-here" }
    }
  }
}

Claude Desktop

Adicione ao claude_desktop_config.json:

{
  "mcpServers": {
    "hetzner": {
      "command": "npx",
      "args": ["-y", "@lazyants/hetzner-mcp-server"],
      "env": {
        "HETZNER_API_TOKEN": "your-token-here"
      }
    }
  }
}

Ferramentas

As ferramentas de listagem primária expõem sort para servidores, volumes, redes, firewalls, balanceadores de carga, IPs, certificados, chaves SSH e grupos de posicionamento. A listagem de imagens também suporta bound_to (um ID de servidor ou um array) e include_deprecated. As métricas de servidor e balanceador de carga aceitam step em segundos; a criação de redes aceita expose_routes_to_vswitch.

Defina resource em hetzner_get_pricing para server_types, load_balancer_types, volume, floating_ips, primary_ips, traffic, image ou server_backup para reduzir a resposta. Os resultados filtrados preservam moeda e IVA; traffic seleciona tráfego incluído específico do local e preços de tráfego adicional para tipos de servidor e balanceador de carga.

Espera de ação (1 ferramenta compartilhada) — cada ponto de entrada

hetzner_wait_for_action aceita domain, resource_id, action_id e um timeout opcional em segundos (padrão 300, máximo 3600). Ele consulta o histórico de ações paginado por recurso e retorna a ação completa quando seu status se torna success ou error; status ausentes ou desconhecidos continuam esperando até o tempo limite. Os domínios suportados são servidores, balanceadores_de_carga, volumes, redes, firewalls, IPs_flutuantes, IPs_primários, certificados, imagens, zonas e storage_boxes; Storage Boxes usam seu host de API separado. O prazo limita solicitações e atrasos de limite de taxa, e o cancelamento do MCP interrompe a espera.

Servidores (27 ferramentas) — servidores

hetzner_list_servers, hetzner_get_server, hetzner_create_server, hetzner_update_server, hetzner_delete_server, hetzner_power_on, hetzner_power_off, hetzner_reboot, hetzner_reset, hetzner_shutdown, hetzner_rebuild_server, hetzner_resize_server, hetzner_enable_rescue, hetzner_disable_rescue, hetzner_get_server_metrics, hetzner_list_server_actions, hetzner_change_server_protection, hetzner_request_console, hetzner_enable_backup, hetzner_disable_backup, hetzner_change_alias_ips, hetzner_change_dns_ptr, hetzner_attach_server_to_network, hetzner_detach_server_from_network, hetzner_add_server_to_placement_group, hetzner_remove_server_from_placement_group, hetzner_reset_server_password

Imagens (7 ferramentas) — armazenamento

hetzner_list_images, hetzner_get_image, hetzner_update_image, hetzner_delete_image, hetzner_create_image, hetzner_change_image_protection, hetzner_list_image_actions

ISOs (4 ferramentas) — configuração

hetzner_list_isos, hetzner_get_iso, hetzner_attach_iso, hetzner_detach_iso

Grupos de Posicionamento (5 ferramentas) — configuração

hetzner_list_placement_groups, hetzner_get_placement_group, hetzner_create_placement_group, hetzner_update_placement_group, hetzner_delete_placement_group

Dados de Referência (5 ferramentas) — servidores

hetzner_list_locations, hetzner_get_location, hetzner_list_server_types, hetzner_get_server_type, hetzner_get_pricing

A Hetzner removeu os endpoints /datacenters após 2026-10-01 (HTTP 410), e este servidor não expõe mais hetzner_list_datacenters ou hetzner_get_datacenter. Use hetzner_list_server_types (locations[].available/recommended) e hetzner_list_locations para informações de disponibilidade e região.

Redes (13 ferramentas) — rede

hetzner_list_networks, hetzner_list_network_members, hetzner_get_network, hetzner_create_network, hetzner_update_network, hetzner_delete_network, hetzner_add_subnet, hetzner_delete_subnet, hetzner_add_route, hetzner_delete_route, hetzner_change_network_protection, hetzner_change_ip_range, hetzner_list_network_actions

hetzner_list_network_members retorna servidores anexados e balanceadores de carga com IPs, aliases, sub-rede e status de anexo. Passe uma string ou array para type, subnet, status e sort; arrays produzem chaves de consulta repetidas. Os resultados incluem os metadados de paginação da API.

Firewalls (9 ferramentas) — rede

hetzner_list_firewalls, hetzner_get_firewall, hetzner_create_firewall, hetzner_update_firewall, hetzner_delete_firewall, hetzner_set_firewall_rules, hetzner_apply_firewall, hetzner_remove_firewall, hetzner_list_firewall_actions

Balanceadores de Carga (21 ferramentas) — balanceadores-de-carga

hetzner_list_load_balancers, hetzner_get_load_balancer, hetzner_create_load_balancer, hetzner_update_load_balancer, hetzner_delete_load_balancer, hetzner_add_lb_target, hetzner_remove_lb_target, hetzner_add_lb_service, hetzner_update_lb_service, hetzner_delete_lb_service, hetzner_change_lb_algorithm, hetzner_change_lb_type, hetzner_attach_lb_to_network, hetzner_detach_lb_from_network, hetzner_get_lb_metrics, hetzner_list_lb_types, hetzner_change_load_balancer_protection, hetzner_list_load_balancer_actions, hetzner_enable_lb_public_interface, hetzner_disable_lb_public_interface, hetzner_change_lb_dns_ptr

Certificados (7 ferramentas) — balanceadores-de-carga

hetzner_list_certificates, hetzner_get_certificate, hetzner_create_certificate, hetzner_update_certificate, hetzner_delete_certificate, hetzner_retry_certificate, hetzner_list_certificate_actions

Volumes (10 ferramentas) — armazenamento

hetzner_list_volumes, hetzner_get_volume, hetzner_create_volume, hetzner_update_volume, hetzner_delete_volume, hetzner_attach_volume, hetzner_detach_volume, hetzner_resize_volume, hetzner_change_volume_protection, hetzner_list_volume_actions

IPs Flutuantes (10 ferramentas) — ips

hetzner_list_floating_ips, hetzner_get_floating_ip, hetzner_create_floating_ip, hetzner_update_floating_ip, hetzner_delete_floating_ip, hetzner_assign_floating_ip, hetzner_unassign_floating_ip, hetzner_change_floating_ip_rdns, hetzner_change_floating_ip_protection, hetzner_list_floating_ip_actions

IPs Primários (10 ferramentas) — ips

hetzner_list_primary_ips, hetzner_get_primary_ip, hetzner_create_primary_ip, hetzner_update_primary_ip, hetzner_delete_primary_ip, hetzner_assign_primary_ip, hetzner_unassign_primary_ip, hetzner_change_primary_ip_rdns, hetzner_change_primary_ip_protection, hetzner_list_primary_ip_actions

Chaves SSH (5 ferramentas) — configuração

hetzner_list_ssh_keys, hetzner_get_ssh_key, hetzner_create_ssh_key, hetzner_update_ssh_key, hetzner_delete_ssh_key

Zonas DNS (22 ferramentas) — dns

hetzner_list_zones, hetzner_get_zone, hetzner_create_zone, hetzner_update_zone, hetzner_delete_zone, hetzner_change_zone_protection, hetzner_change_zone_ttl, hetzner_change_zone_primary_nameservers, hetzner_export_zonefile, hetzner_import_zonefile, hetzner_list_zone_actions, hetzner_list_zone_rrsets, hetzner_get_zone_rrset, hetzner_create_zone_rrset, hetzner_update_zone_rrset, hetzner_delete_zone_rrset, hetzner_change_zone_rrset_protection, hetzner_change_zone_rrset_ttl, hetzner_add_zone_rrset_records, hetzner_remove_zone_rrset_records, hetzner_set_zone_rrset_records, hetzner_update_zone_rrset_records

Storage Boxes (29 ferramentas) — storage-boxes

Storage Boxes usam o host https://api.hetzner.com/v1. Token: HETZNER_STORAGE_API_TOKEN (recorre a HETZNER_API_TOKEN).

hetzner_list_storage_boxes, hetzner_create_storage_box, hetzner_get_storage_box, hetzner_update_storage_box, hetzner_delete_storage_box, hetzner_list_storage_box_folders, hetzner_list_storage_box_actions, hetzner_change_storage_box_protection, hetzner_change_storage_box_type, hetzner_reset_storage_box_password, hetzner_update_storage_box_access_settings, hetzner_rollback_storage_box_snapshot, hetzner_enable_storage_box_snapshot_plan, hetzner_disable_storage_box_snapshot_plan, hetzner_list_storage_box_types, hetzner_get_storage_box_type, hetzner_list_storage_box_snapshots, hetzner_create_storage_box_snapshot, hetzner_get_storage_box_snapshot, hetzner_update_storage_box_snapshot, hetzner_delete_storage_box_snapshot, hetzner_list_storage_box_subaccounts, hetzner_create_storage_box_subaccount, hetzner_get_storage_box_subaccount, hetzner_update_storage_box_subaccount, hetzner_delete_storage_box_subaccount, hetzner_change_storage_box_subaccount_home_directory, hetzner_reset_storage_box_subaccount_password, hetzner_update_storage_box_subaccount_access_settings

Segurança

Nunca envie seu token de API para o controle de versão
Use tokens somente leitura quando você precisar apenas listar/obter recursos
Ferramentas de criar e excluir custam dinheiro real — a Hetzner cobra pelos recursos provisionados
O servidor lida com a limitação de taxa automaticamente (3.600 solicitações/hora, backoff exponencial em 429)

Aviso Legal

Operações de criar, atualizar e excluir podem gerar cobranças na sua conta Hetzner Cloud. Use tokens de API somente leitura quando possível. Os autores não são responsáveis por quaisquer custos incorridos.

Lançamento

Os lançamentos são enviados via evento de Release do GitHub. Fluxo do mantenedor:

Aumente a versão em package.json e server.json (ambos #/version e #/packages[0].version), depois execute npm install --package-lock-only para sincronizar package-lock.json. node scripts/check-versions.mjs falha de forma rígida a menos que package.json#/version corresponda a server.json#/packages[0].version; server.json#/version é verificado de forma flexível — pode legitimamente estar à frente (republicações somente de registro aumentam apenas esse campo), então um valor desatualizado passa com uma linha WARN: e sem falha. Leia a saída do script em vez de confiar no código de saída. CHANGELOG.md não é verificado de forma alguma.
Atualize CHANGELOG.md.
Faça commit e mescle o aumento de versão em main antes de criar o release. Depois crie a tag você mesmo, em um SHA que você verificou, e só então crie o release a partir dela:
```
V=X.Y.Z && PR=<release-pr-number> &&
  SHA="$(gh pr view "$PR" --json mergeCommit -q .mergeCommit.oid)" && test -n "$SHA" &&
  git fetch origin main && git merge-base --is-ancestor "$SHA" origin/main &&
  PKG="$(git show "$SHA:package.json")" &&
  test "$(printf '%s' "$PKG" | node -pe 'JSON.parse(require("fs").readFileSync(0,"utf8")).version')" = "$V" &&
  CL="$(git show "$SHA:CHANGELOG.md")" &&
  printf '%s\n' "$CL" | awk -v v="$V" 'index($0,"## ["v"]")==1{f=1;next} /^## \[/{f=0} /^\[[0-9]+\.[0-9]+\.[0-9]+\]:/{f=0} f' > "/tmp/notes-v$V.md" &&
  grep -q '[^[:space:]]' "/tmp/notes-v$V.md" &&
  git tag -a "v$V" "$SHA" -m "v$V" &&
  git push origin "v$V" &&
  gh release create "v$V" --verify-tag --notes-file "/tmp/notes-v$V.md"
```
Nunca execute um gh release create vX.Y.Z simples. Sem uma tag existente, ele coloca uma na ponta do branch padrão, então executá-lo enquanto o aumento ainda está em um branch de release marca o commit do release anterior. O fluxo de trabalho então publica qualquer versão que encontrar no package.json desse commit, e você obtém um GitHub Release vX.Y.Z que republica silenciosamente a versão antiga. O fluxo de trabalho de publicação agora se recusa a continuar quando GITHUB_REF_NAME não é v<package.json version>, então esse cenário exato falha antes de npm publish em vez de republicar silenciosamente. A sequência acima ainda é necessária e protege um caso que o fluxo de trabalho não pode: a proteção do fluxo de trabalho só é executada quando um release já existe, e passa para qualquer commit que carregue a versão correta — então ela detecta um release com tag incorreta, não o commit errado sendo marcado.

Cada elemento é essencial:

gh pr view … .mergeCommit.oid nomeia o commit de squash do próprio PR de release. Não substitua por git rev-parse origin/main — isso é meramente o que estiver em main no momento em que você olhar, então um merge não relacionado que chegar nesse intervalo seria marcado e publicado em seu lugar. gh sai com código 0 e não imprime nada para um PR não mesclado, daí o test -n explícito.
- A cadeia && para na primeira falha em vez de cair na etapa irreversível. Ambas as chamadas git show são atribuídas a uma variável em vez de serem canalizadas diretamente, então seu status de saída é realmente verificado — um pipeline reporta apenas o status do último comando, a menos que pipefail esteja definido, o que não é assumido aqui.
- git merge-base --is-ancestor prova que o commit é alcançável a partir de main. A mera existência não é suficiente — um commit pode estar presente localmente porque algum outro branch foi buscado.
- O teste de versão lê package.json do commit de destino, não da árvore de trabalho, que ainda mostraria a versão correta enquanto $SHA apontasse para outro lugar.
- O awk extrai a seção dessa versão do CHANGELOG.md do commit para --notes-file. Ele para no próximo cabeçalho ## [ ou na primeira definição de referência de link, porque a entrada mais antiga não tem cabeçalho depois dela e, de outra forma, engoliria todo o bloco de referências de link. grep -q em vez de test -s protege o resultado: uma seção vazia exceto por sua linha em branco ainda produz um arquivo de um byte, que test -s aceita.

O workflow Publish to npm + MCP Registry roda automaticamente: ele npm publish com proveniência, consulta o registro até o tarball estar disponível e então envia o server.json correspondente para o MCP Registry via mcp-publisher.

O workflow pula npm publish limpo se a versão já estiver no npm (proteção de corte para releases que foram parcialmente publicados manualmente).

Autenticação npm

A publicação usa npm Trusted Publishing: o token OIDC do GitHub do workflow (id-token: write) é trocado por um token de publicação único em tempo de execução. Nenhum segredo NPM_TOKEN precisa viver no repositório.

A vinculação é configurada na interface web do npm (pacote → Trusted Publishers): provedor GitHub Actions, organização lazyants, repositório hetzner-mcp-server, workflow publish-registry.yml.

Licença

FSL-1.1-MIT — veja LICENSE para os termos completos. Versões 1.1.1 e anteriores permanecem licenciadas sob MIT.