mcp-hetzner

Hetzner Cloud MCP Server

A Model Context Protocol (MCP) server for interacting with the Hetzner Cloud API. This server allows language models to manage Hetzner Cloud resources through structured functions.

Features

• List, create, and manage Hetzner Cloud servers
• Create, attach, detach, and resize volumes
• Manage firewall rules and apply them to servers
• Create and manage SSH keys for secure server access
• View available images, server types, and locations
• Power on/off and reboot servers
• Simple, structured API for language model interaction
• Claude Code integration for managing Hetzner resources directly from Claude

Requirements

• Python 3.11+
• Hetzner Cloud API token

Installation

Method 1: Direct Installation

1. Clone this repository:

git clone https://github.com/dkruyt/mcp-hetzner.git
cd mcp-hetzner

2. Install dependencies:

pip install -e .

3. Create a .env file and add your Hetzner Cloud API token:

HCLOUD_TOKEN=your_hetzner_cloud_api_token_here

Method 2: Install as a Package

# Install directly from the repository
pip install git+https://github.com/dkruyt/mcp-hetzner.git

After installing as a package, create a .env file in your working directory with your Hetzner Cloud API token.

Usage

Starting the Server

Option 1: Run the installed package:

# Using default stdio transport
mcp-hetzner

# Using SSE transport
mcp-hetzner --transport sse

# Setting a custom port
mcp-hetzner --transport sse --port 8000

Option 2: Run as a module:

python -m mcp_hetzner
# or
python -m mcp_hetzner.server

The server supports two transport modes:

• stdio (default): Standard I/O transport, typically used with Claude Code
• sse: Server-Sent Events transport, suitable for HTTP clients

By default, the server runs on localhost:8080. You can customize the host and port by:

1. Setting the MCP_HOST and MCP_PORT environment variables in your .env file
2. Using the --port command line argument (overrides the environment variable)

Using with Claude Code

To use with Claude Code, run the server with SSE transport:

# Start the server with SSE transport
mcp-hetzner --transport sse --port 8080

# In another terminal, connect Claude Code to the server
claude-code --mcp-server localhost:8080

Testing the API

A test client is included to verify the server functionality:

python -m mcp_hetzner.client

Example Workflows

Basic Server Management

# List all your servers
list_servers

# Create a new server
create_server {
  "name": "web-server", 
  "server_type": "cx11", 
  "image": "ubuntu-22.04"
}

# Power operations
power_off {"server_id": 12345}
power_on {"server_id": 12345}
reboot {"server_id": 12345}

# Delete a server when no longer needed
delete_server {"server_id": 12345}

Volume Management

# List all volumes
list_volumes

# Create a new volume
create_volume {
  "name": "data-volume",
  "size": 10,
  "location": "nbg1",
  "format": "ext4"
}

# Attach volume to a server
attach_volume {
  "volume_id": 12345,
  "server_id": 67890,
  "automount": true
}

# Detach volume from server
detach_volume {
  "volume_id": 12345
}

# Resize a volume (can only increase size)
resize_volume {
  "volume_id": 12345,
  "size": 50
}

# Delete a volume when no longer needed
delete_volume {
  "volume_id": 12345
}

Firewall Management

# List all firewalls
list_firewalls

# Create a firewall for web servers
create_firewall {
  "name": "web-firewall",
  "rules": [
    {
      "direction": "in",
      "protocol": "tcp",
      "port": "80",
      "source_ips": ["0.0.0.0/0", "::/0"]
    },
    {
      "direction": "in",
      "protocol": "tcp",
      "port": "443",
      "source_ips": ["0.0.0.0/0", "::/0"]
    }
  ]
}

# Apply firewall to a server
apply_firewall_to_resources {
  "firewall_id": 12345,
  "resources": [
    {
      "type": "server",
      "server_id": 67890
    }
  ]
}

SSH Key Management

# List all SSH keys
list_ssh_keys

# Create a new SSH key
create_ssh_key {
  "name": "my-laptop",
  "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAA... user@laptop"
}

# Use the SSH key when creating a server
create_server {
  "name": "secure-server",
  "server_type": "cx11",
  "image": "ubuntu-22.04",
  "ssh_keys": [12345]
}

# Update an SSH key's name
update_ssh_key {
  "ssh_key_id": 12345,
  "name": "work-laptop"
}

# Delete an SSH key
delete_ssh_key {
  "ssh_key_id": 12345
}

Infrastructure Planning

# Explore available resources
list_server_types
list_images
list_locations

# Get specific server information
get_server {"server_id": 12345}

Available Functions

The MCP server provides the following functions:

Server Management

• list_servers: List all servers in your Hetzner Cloud account
• get_server: Get details about a specific server
• create_server: Create a new server
• delete_server: Delete a server
• power_on: Power on a server
• power_off: Power off a server
• reboot: Reboot a server

Volume Management

• list_volumes: List all volumes in your Hetzner Cloud account
• get_volume: Get details about a specific volume
• create_volume: Create a new volume
• delete_volume: Delete a volume
• attach_volume: Attach a volume to a server
• detach_volume: Detach a volume from a server
• resize_volume: Increase the size of a volume

Firewall Management

• list_firewalls: List all firewalls in your Hetzner Cloud account
• get_firewall: Get details about a specific firewall
• create_firewall: Create a new firewall
• update_firewall: Update firewall name or labels
• delete_firewall: Delete a firewall
• set_firewall_rules: Set or update firewall rules
• apply_firewall_to_resources: Apply a firewall to servers or server groups
• remove_firewall_from_resources: Remove a firewall from servers or server groups

SSH Key Management

• list_ssh_keys: List all SSH keys in your Hetzner Cloud account
• get_ssh_key: Get details about a specific SSH key
• create_ssh_key: Create a new SSH key
• update_ssh_key: Update SSH key name or labels
• delete_ssh_key: Delete an SSH key

Information

• list_images: List available OS images
• list_server_types: List available server types
• list_locations: List available datacenter locations

License

MIT