Hetzner MCP Server

An MCP server that lets Claude Code manage your Hetzner Cloud servers.

npm install -g hetzner-mcp-server

What is MCP?

MCP (Model Context Protocol) is a way for AI assistants like Claude to interact with external services and APIs. Think of it like giving Claude "hands" to do things on your behalf.

How it works:

1. You install an MCP server (like this one) on your computer
2. You configure Claude Code to use it
3. Claude can now use "tools" that the MCP server provides
4. When you ask Claude to "create a server", it uses these tools to actually do it

Your understanding is correct: MCP exposes certain API capabilities as tool calls for the AI agent. The AI can then decide when to use these tools to help you accomplish tasks.

What is Hetzner Cloud?

Hetzner is a cloud hosting provider (like AWS, DigitalOcean, or Linode) where you can rent virtual servers. You pay by the hour for the servers you use.

What is a "Project" in Hetzner?

A Project is like a folder or container that groups related resources together. When you sign up for Hetzner Cloud:

1. You create Projects to organize your work (e.g., "My Blog", "Client Website", "Test Environment")
2. Inside each project, you create Servers (the actual virtual machines)
3. Each project also contains related resources: SSH keys, firewall rules, networks, etc.

Example: You might have:

• Project "Personal Blog" → 1 server running your blog
• Project "Client Work" → 3 servers for different client websites
• Project "Testing" → Temporary servers you spin up and delete

Each project is completely separate - servers in one project can't see servers in another.

What Can This MCP Do?

It CAN:

• Create servers (this costs money!)
• Delete servers (permanent, irreversible)
• Power on/off servers (like pressing the power button)
• Reboot servers
• List all your servers and see their details (IP address, status, specs)
• Manage SSH keys (the keys used to log into your servers)
• Show available options (server sizes, OS images, datacenter locations)

It CANNOT:

• Create new Projects (you do that manually in the Hetzner web console)
• Manage billing or payment methods
• Access other projects (it only sees the project whose token you provide)
• Manage advanced features like load balancers, volumes, or firewalls (not implemented yet)

Important: This Can Spend Your Money!

When you create a server through this MCP, Hetzner will charge you real money. Servers are billed hourly. For example:

• A small cx22 server costs ~€0.006/hour (~€4/month)
• A larger cx52 server costs ~€0.119/hour (~€86/month)

Always check pricing with hetzner_list_server_types before creating servers, and delete servers you're not using to avoid charges.

Hetzner MCP + Kamal = Your Own PaaS

Combine this MCP with Kamal (DHH's deployment tool) and the kamal-deploy skill to get a complete deployment platform inside Claude Code.

The mental model:

• Hetzner MCP = Provisions the servers (the computers)
• Kamal = Deploys your app to those servers (the software)
• Together = Your own Vercel/Render/Hatchbox alternative

Feature Comparison

| Feature | Hetzner MCP + Kamal | Hatchbox | Vercel | Render | |---------|---------------------|----------|--------|--------| | Create/manage servers | ✅ Via MCP | ✅ Web UI | ❌ Serverless | ✅ Managed | | Deploy apps | ✅ Kamal | ✅ Git push | ✅ Git push | ✅ Git push | | Zero-downtime deploys | ✅ | ✅ | ✅ | ✅ | | SSL certificates | ✅ Let's Encrypt | ✅ Auto | ✅ Auto | ✅ Auto | | Databases | ✅ Kamal accessories | ✅ Managed | ❌ External | ✅ Managed | | Redis | ✅ Kamal accessories | ✅ Managed | ❌ External | ✅ Managed | | Background jobs | ✅ Kamal workers | ✅ Sidekiq | ⚠️ Cron only | ✅ Workers | | Rollback | ✅ kamal rollback | ✅ One-click | ✅ One-click | ✅ One-click | | Custom domains | ✅ | ✅ | ✅ | ✅ | | SSH access to server | ✅ Full root | ✅ Limited | ❌ None | ❌ None | | Docker support | ✅ Native | ❌ No | ✅ Yes | ✅ Yes | | Non-Ruby apps | ✅ Any Docker app | ❌ Ruby only | ✅ Any | ✅ Any | | Multiple apps per server | ✅ Manual | ✅ Clusters | N/A | N/A | | Web UI dashboard | ❌ CLI only | ✅ | ✅ | ✅ | | Automatic backups | ❌ DIY | ✅ | N/A | ✅ | | Managed security updates | ❌ DIY | ✅ | ✅ | ✅ | | Monitoring/alerts | ❌ DIY | ✅ | ✅ | ✅ |

Cost Comparison (typical Rails app)

| Platform | Monthly Cost | What You Get | |----------|--------------|--------------| | Hetzner + Kamal | ~€4-8/mo | Full server, unlimited apps | | Hatchbox | $10-29/mo + server | Managed Rails deployment | | Vercel | $20+/mo | Serverless, limited compute | | Render | $7-25/mo per service | Managed containers |

When to Use What

Choose Hetzner MCP + Kamal if you:

• Want full control over your infrastructure
• Are comfortable with CLI (Claude helps!)
• Want the cheapest option for production apps
• Need to run any Docker-based app (not just Rails)
• Want to learn how deployment actually works

Choose Hatchbox if you:

• Only deploy Rails apps
• Want a polished web UI
• Need team access management
• Prefer fully managed backups/updates
• Don't want to think about servers

Choose Vercel if you:

• Build Next.js/frontend apps
• Want zero server management
• Need edge functions/CDN
• Don't need persistent servers

Choose Render if you:

• Want managed containers without complexity
• Need managed databases included
• Want simple scaling
• Prefer web UI over CLI

Quick Start with Kamal

1. Install the kamal-deploy skill from claude-code-essentials
2. Ask Claude: "Create a cx22 server with Ubuntu for my-app" (uses this MCP)
3. Ask Claude: "Help me set up Kamal to deploy my Rails app to this server"
4. Run kamal setup and you're live!

How Authentication Works

The API Token

To use Hetzner's API, you need an API Token. This is like a password that:

1. Proves you are who you say you are
2. Grants access to a specific project
3. Has permission levels (read-only or read+write)

One token = One project. If you have 3 projects and want Claude to manage all of them, you'd need 3 different tokens (and 3 MCP configurations).

Token Permissions

When you create a token, you choose its permissions:

• Read: Can view servers, list resources, but can't change anything
• Read & Write: Can view AND create/delete/modify resources

For this MCP to be useful, you need Read & Write permissions.

Security Considerations

Your API token is powerful - anyone with it can create/delete servers in your project. Keep it safe:

1. Never share your token or commit it to git
2. Store it in environment variables, not in code
3. Use a dedicated project for testing so mistakes don't affect production
4. Delete unused tokens in the Hetzner console
5. Review what Claude is doing before confirming destructive actions

Storage Boxes — Different Token Required

Storage Box tools (hetzner_list_storage_boxes, hetzner_get_storage_box, hetzner_list_storage_box_subaccounts, hetzner_list_storage_box_snapshots, hetzner_create_storage_box_snapshot, hetzner_rollback_storage_box_snapshot) use Hetzner's unified API at api.hetzner.com/v1, which is not the same as the Cloud API used by all the other tools. The two APIs accept different token classes:

| Tool category | API endpoint | Token source | |---|---|---| | Servers, SSH keys, reference | api.hetzner.cloud/v1 | Cloud project tokens | | Storage Boxes | api.hetzner.com/v1 | Account-level unified tokens |

A Cloud-project token does NOT authenticate against the unified API. If you only set HETZNER_API_TOKEN to a Cloud token, Storage Box tools will return 401 Unauthorized.

Two ways to configure:

1. Single unified token (simplest): Generate a unified token from console.hetzner.com/account/security/api-tokens and set HETZNER_API_TOKEN to it. The unified token authenticates against both APIs.
2. Separate tokens (recommended for least-privilege): Set HETZNER_API_TOKEN to a Cloud-project token AND HETZNER_API_TOKEN_UNIFIED to a unified token. The Storage Box client will prefer HETZNER_API_TOKEN_UNIFIED.

If neither variable is set when a Storage Box tool is invoked, you'll get a clear error pointing at the unified-token console URL.

Getting an API Token

1. Go to Hetzner Cloud Console
2. Click on the project you want to manage (or create a new one)
3. In the left sidebar, click Security
4. Click API Tokens
5. Click Generate API Token
6. Enter a name (e.g., "Claude Code MCP")
7. Select Read & Write permissions
8. Click Generate API Token
9. Copy the token immediately - it won't be shown again!

Installation

Prerequisites

• Node.js 18 or higher
• npm
• A Hetzner Cloud account with an API token

Option 1: Install from npm (Recommended)

npm install -g hetzner-mcp-server

Then configure Claude Code to use it (see below).

Option 2: Clone and Build

# Clone the repository
git clone https://github.com/nityeshaga/hetzner-mcp-server.git
cd hetzner-mcp-server

# Install dependencies
npm install

# Build the TypeScript code
npm run build

Configuring Claude Code

Add the MCP server config to ~/.claude.json (your user-level Claude Code config file).

Important: The config goes in ~/.claude.json, NOT ~/.claude/settings.json or ~/.claude/.mcp.json. Run /mcp in Claude Code to verify the correct config location for your setup.

If installed via npm (Option 1):

Open ~/.claude.json and add hetzner to the mcpServers object:

{
  "mcpServers": {
    "hetzner": {
      "type": "stdio",
      "command": "npx",
      "args": ["hetzner-mcp-server"],
      "env": {
        "HETZNER_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

If you already have other MCP servers configured (like figma), just add hetzner alongside them:

{
  "mcpServers": {
    "figma": { ... },
    "hetzner": {
      "type": "stdio",
      "command": "npx",
      "args": ["hetzner-mcp-server"],
      "env": {
        "HETZNER_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

If cloned from GitHub (Option 2):

{
  "mcpServers": {
    "hetzner": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/hetzner-mcp-server/dist/index.js"],
      "env": {
        "HETZNER_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Replace /path/to/hetzner-mcp-server with the actual path where you cloned the repo.

Replace your-api-token-here with your actual Hetzner API token.

Then restart Claude Code for the changes to take effect.

Using the MCP

Once configured, you can talk to Claude naturally:

Viewing Resources

• "List all my servers"
• "Show me server 12345"
• "What SSH keys do I have?"
• "What server types are available and how much do they cost?"
• "What locations can I deploy to?"
• "What OS images are available?"

Creating Servers

• "Create a new server called my-app with Ubuntu 24.04"
• "Spin up a cx22 server in Falkenstein running Debian"
• "Create a server named test-server with my SSH key attached"

Managing Servers

• "Power off server 12345"
• "Reboot my-app server"
• "Delete the test-server" (be careful - this is permanent!)

Managing SSH Keys

• "Add my SSH public key" (then paste the key)
• "List my SSH keys"
• "Delete SSH key 789"

Available Tools (20 total)

Server Tools (7)

| Tool | What it does | |------|--------------| | hetzner_list_servers | Shows all servers in the project | | hetzner_get_server | Shows details of one server (IP, status, specs) | | hetzner_create_server | Creates a new server (costs money!) | | hetzner_delete_server | Permanently deletes a server | | hetzner_power_on_server | Turns on a powered-off server | | hetzner_power_off_server | Hard power off (like pulling the plug) | | hetzner_reboot_server | Hard reboot (like pressing reset button) |

SSH Key Tools (4)

| Tool | What it does | |------|--------------| | hetzner_list_ssh_keys | Shows all SSH keys in the project | | hetzner_get_ssh_key | Shows details of one SSH key | | hetzner_create_ssh_key | Adds a new SSH public key | | hetzner_delete_ssh_key | Removes an SSH key |

Reference Tools (3)

| Tool | What it does | |------|--------------| | hetzner_list_server_types | Shows available sizes and prices | | hetzner_list_images | Shows available operating systems | | hetzner_list_locations | Shows available datacenters |

Storage Box Tools (6) — uses unified API token (see Storage Boxes — Different Token Required)

| Tool | What it does | |------|--------------| | hetzner_list_storage_boxes | Lists all Storage Boxes (auto-paginates, cap 5 pages × 50) | | hetzner_get_storage_box | Shows details of one Storage Box | | hetzner_list_storage_box_subaccounts | Lists subaccounts for a Storage Box (auto-paginates) | | hetzner_list_storage_box_snapshots | Lists snapshots for a Storage Box (auto-paginates) | | hetzner_create_storage_box_snapshot | Triggers an on-demand snapshot (optional description / labels) | | hetzner_rollback_storage_box_snapshot | Destructive — rolls a Storage Box back to a snapshot (overwrites data) |

Example Workflow

Here's how you might use this MCP to deploy a new project:

1. Check what's available

You: "What server types are available?"
Claude: [Lists server types with CPU, RAM, disk, and pricing]

You: "What locations can I use?"
Claude: [Lists Falkenstein, Nuremberg, Helsinki, etc.]

2. Add your SSH key (if not already added)

You: "Add my SSH key called 'my-laptop'"
Claude: "What's the public key content?"
You: [Paste your ~/.ssh/id_rsa.pub content]
Claude: "SSH key 'my-laptop' created with ID 12345"

3. Create a server

You: "Create a cx22 server with Ubuntu 24.04 in Falkenstein, name it my-app, and use my SSH key"
Claude: "Server 'my-app' created!
  - ID: 67890
  - IP: 123.45.67.89
  - Status: initializing
  SSH key authentication is configured."

4. Connect to your server

ssh [email protected]

5. When done, delete the server (to stop charges)

You: "Delete server my-app"
Claude: "Are you sure? This is permanent."
You: "Yes, delete it"
Claude: "Server 67890 is being deleted."

Troubleshooting

"HETZNER_API_TOKEN environment variable is required"

You haven't configured the token in your Claude Code settings. Make sure:

1. The token is in ~/.claude/settings.json
2. You've restarted Claude Code

"Error: Authentication failed"

Your API token is invalid. Generate a new one in the Hetzner console.

"Error: Permission denied"

Your token doesn't have write permissions. Generate a new token with "Read & Write".

"Error: Resource not found"

The server/SSH key ID doesn't exist. Use the list commands to see what's available.

Development

# Install dependencies
npm install

# Build (compile TypeScript to JavaScript)
npm run build

# Development mode (auto-rebuild on changes)
npm run dev

License

MIT