HCloud MCP

Standalone MCP (Model Context Protocol) server for the Hetzner Cloud API. Use it with any MCP client: Cursor, Claude Desktop, CLI tools, smithery.ai, or custom agents.

• Repository: github.com/Xodus-CO/hcloud-mcp
• Cursor Plugin: github.com/Xodus-CO/hetzner-mcp — install from the Cursor Plugin marketplace.
• Hetzner Cloud: Get started — new signups get €20 credit.

---

Requirements

• Node.js 18+
• A Hetzner Cloud API token. Generate one in the console (project → Security → API Tokens). Set it as HCLOUD_TOKEN in the environment or in your MCP client config.

Installation

From npm (recommended)

npm install -g hcloud-mcp

Or use npx to run without a global install.

From source

git clone https://github.com/Xodus-CO/hcloud-mcp
cd hcloud-mcp
npm install
npm run build

Configuration

Add the server to your MCP client config. It uses MCP over stdio and requires HCLOUD_TOKEN in the environment.

Example — mcp.json (or your client’s equivalent) using the npm binary:

{
  "mcpServers": {
    "hetzner-cloud": {
      "command": "npx",
      "args": ["hcloud-mcp"],
      "env": {
        "HCLOUD_TOKEN": "your_hetzner_cloud_api_token"
      }
    }
  }
}

If you installed from source, use an absolute path to run.js in args so the server runs from the project directory (e.g. when the MCP client’s CWD is different, as in dev containers):

"command": "node",
"args": ["/path/to/hcloud-mcp/run.js"]

Replace /path/to/hcloud-mcp with your actual project path (e.g. /home/<username>/hcloud-mcp).

Tools

The server exposes Hetzner Cloud API operations as MCP tools:

Area	Tools
Servers	list_servers, get_server, create_server, delete_server, update_server, change_server_type; power: power_on_server, power_off_server, reboot_server, shutdown_server, reset_server; attach_iso, detach_iso; attach_server_to_network, detach_server_from_network
Load Balancers	list_load_balancers, get_load_balancer, create_load_balancer, update_load_balancer, delete_load_balancer; add_load_balancer_target, remove_load_balancer_target; add_load_balancer_service, update_load_balancer_service, delete_load_balancer_service; list_load_balancer_types
Networks	list_networks, get_network, create_network, update_network, delete_network; add_network_subnet, delete_network_subnet
Volumes	list_volumes, get_volume, create_volume, update_volume, delete_volume; attach_volume, detach_volume
Firewalls	list_firewalls, get_firewall, create_firewall, update_firewall, delete_firewall; apply_firewall_to_resources, remove_firewall_from_resources, set_firewall_rules
Floating IPs	list_floating_ips, create_floating_ip, update_floating_ip, delete_floating_ip; assign_floating_ip, unassign_floating_ip
Primary IPs	list_primary_ips, create_primary_ip, get_primary_ip, update_primary_ip, delete_primary_ip; assign_primary_ip, unassign_primary_ip (server must be off)
SSH Keys	list_ssh_keys, create_ssh_key, update_ssh_key, delete_ssh_key
Placement Groups	list_placement_groups, create_placement_group, update_placement_group, delete_placement_group
Metadata & actions	list_locations, list_images, list_server_types, list_load_balancer_types, list_datacenters, get_pricing; list_actions, get_action (poll async operations)

Note: Subnets (not networks) are scoped to a network_zone (e.g., eu-central). Each Subnet has a network_zone; all Subnets within a Network share the same network_zone. Servers must be created in locations that match the Subnet's network_zone, so resources in the Network are constrained by the shared subnet network_zone.

Usage examples

With the MCP client connected, you can ask the agent to run tools using natural language.

Simple

• List my servers in Nuremberg
• Create a cx22 server with Ubuntu 24.04
• Create a cx22 server with Ubuntu 24.04 using my SSH key 'macbook'
• Attach a 10GB volume to web-01
• Set up a load balancer for my web servers
• List load balancer types
• Show current pricing for cpx31 servers
• Get status of action 12345

Complex

• Create a private network 10.0.0.0/16 in eu-central, add a subnet, then create two servers in that zone (e.g. fsn1 and nbg1) and attach them
• Create a firewall for SSH and HTTP, attach to my web servers, then create a load balancer and add those servers as targets
• List running actions and get status of action 12345
• Create a Primary IP in ash-dc1, power off web-01, assign the IP, power back on
• Create a 20GB volume and a cx22 server in nbg1, attach the volume to the server, and show me the device path
• Power off server 12345, change its type to cpx31, then power it back on
• Add server web-02 as a target to my load balancer prod-lb
• Tear down: detach/delete volumes, delete LB and firewall, unassign/delete floating IPs, delete servers web-01 and web-02

Development

File	Purpose
src/index.ts	Entry point, stdio transport, HCLOUD_TOKEN check
src/register-tools.ts	Tool definitions and Hetzner API calls (uses SDK McpServer)

Scripts:

npm run build   # compile
npm run start   # run (requires HCLOUD_TOKEN)
npm run dev     # watch and recompile
npm run test:api   # test list_* Hetzner API calls (requires HCLOUD_TOKEN)
npm run test:mcp   # integration test: MCP client calls list_locations (requires HCLOUD_TOKEN)
npm run audit:api  # verify create_* request body shapes (DRY_RUN=1, no resources created)

License

MIT