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

---

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 (14 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

---

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 root@123.45.67.89

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