# HCloud MCP
Standalone **MCP (Model Context Protocol) server** for the [Hetzner Cloud API](https://docs.hetzner.cloud/). Use it with any MCP client: Cursor, Claude Desktop, CLI tools, [smithery.ai](https://smithery.ai), or custom agents.
- **Repository:** [github.com/Xodus-CO/hcloud-mcp](https://github.com/Xodus-CO/hcloud-mcp)
- **Cursor Plugin:** [github.com/Xodus-CO/hetzner-mcp](https://github.com/Xodus-CO/hetzner-mcp) — install from the Cursor Plugin marketplace.
- **Hetzner Cloud:** [Get started](https://hetzner.cloud/?ref=IAYKetqPnlq9) — new signups get €20 credit.
---
## Requirements
- Node.js 18+
- A Hetzner Cloud API token. [Generate one](https://docs.hetzner.com/cloud/api/getting-started/generating-api-token) 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)
```bash
npm install -g hcloud-mcp
```
Or use `npx` to run without a global install.
### From source
```bash
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:
```json
{
"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):
```json
"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:**
```bash
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
