Infrastructure Management Suite

A comprehensive toolkit for managing cloud infrastructure and home servers through AI-powered automation with Claude Code.

🌟 Features

This repository provides unified management capabilities for:

🌩️ Hetzner Cloud Integration

• Server provisioning and management
• SSH key management
• Network configuration
• Via official MCP (Model Context Protocol) server

🏠 Unraid Server Management

• System monitoring and health checks
• Docker container lifecycle management
• Array and storage monitoring
• VM management
• Custom CLI tool with safety features

📋 Table of Contents

• Quick Start
• Prerequisites
• Installation
• Unraid CLI Usage
• Claude Desktop Integration
• Configuration
• Safety Features
• Architecture
• Contributing
• License

🚀 Quick Start

Test Connections

# Test Unraid connection
./unraid test

# View Unraid system info
./unraid system

# List Docker containers
./unraid docker list

Check Your Infrastructure

# View array status
./unraid array

# Check system information
./unraid system

📦 Prerequisites

Required Software

• Python 3.10+ - For Unraid CLI tool
• pipx - For installing MCP servers
• Git - For version control
• curl - For API testing

Required Credentials

1. Hetzner Cloud API Token

   • Get from: https://console.hetzner.cloud/
   • Settings → Security → API Tokens

2. Unraid API Key

   • Generate from: Unraid WebUI → Settings → Management Access → API Keys
   • Requires Unraid OS 7.2+

🔧 Installation

1. Clone the Repository

git clone <your-repo-url>
cd claudecode

2. Configure Environment Variables

Create a .env file with your credentials:

# Hetzner Cloud
HCLOUD_TOKEN=your_hetzner_token_here

# Unraid Server
UNRAID_API_URL=https://homeserver.local/graphql
UNRAID_API_KEY=your_unraid_api_key_here
UNRAID_VERIFY_SSL=false

⚠️ Never commit .env to version control!

3. Set Up Python Environment

# Create virtual environment
python3 -m venv venv

# Activate it
source venv/bin/activate

# Install dependencies
pip install httpx python-dotenv

4. Install MCP Servers

# Install Hetzner MCP server
pipx install mcp-hetzner

# Install Unraid MCP server
pipx install git+https://github.com/jmagar/unraid-mcp.git

5. Make CLI Executable

chmod +x unraid

💻 Unraid CLI Usage

System Information

# Human-readable output
./unraid system

# JSON output
./unraid system --json

Example output:

🖥️  System Information
   OS: Unraid OS 7.2 x86_64
   Hostname: homeserver
   Platform: linux
   Uptime: 2025-11-22T19:55:54.003Z seconds

💻 CPU: Intel Core™ i7-6700K
   Cores: 4, Threads: 8

Docker Management

# List all containers
./unraid docker list

# Start a container
./unraid docker start /plex

# Stop a container (with confirmation)
./unraid docker stop /nginx-proxy-manager

# Stop without confirmation
./unraid docker stop --force /plex

Storage and Array

# Check array status
./unraid array

# List physical disks
./unraid disks

# Get JSON output for scripting
./unraid array --json

Virtual Machines

# List all VMs
./unraid vm list

API Testing

# Test connection
./unraid test

🖥️ Claude Desktop Integration

To use the Unraid MCP server with Claude Desktop:

1. Locate Claude Desktop Config

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

2. Add MCP Server Configuration

Edit the config file and add:

{
  "mcpServers": {
    "unraid": {
      "command": "/Users/hoe/.local/bin/unraid-mcp-server",
      "env": {
        "UNRAID_API_URL": "https://homeserver.local/graphql",
        "UNRAID_API_KEY": "your_api_key_here",
        "UNRAID_VERIFY_SSL": "false"
      }
    },
    "hetzner": {
      "command": "/Users/hoe/.local/bin/mcp-hetzner",
      "env": {
        "HCLOUD_TOKEN": "your_hetzner_token_here"
      }
    }
  }
}

3. Restart Claude Desktop

Close and reopen Claude Desktop. You should see the MCP servers in the tools menu.

4. Verify Integration

In Claude Desktop, you can now ask:

• "What's my Unraid server status?"
• "List my Docker containers"
• "Show my Hetzner Cloud servers"

⚙️ Configuration

Environment Variables

Variable	Description	Example
HCLOUD_TOKEN	Hetzner Cloud API token	abc123...
UNRAID_API_URL	Unraid GraphQL endpoint	https://homeserver.local/graphql
UNRAID_API_KEY	Unraid API key	46e0d5fe...
UNRAID_VERIFY_SSL	Verify SSL certificates	false

File Structure

claudecode/
├── README.md                 # This file
├── UNRAID-README.md         # Detailed Unraid CLI docs
├── CLAUDE.md                # Instructions for Claude Code
├── .env                     # Environment variables (not in git)
├── .gitignore              # Git ignore rules
├── unraid                   # Bash wrapper script
├── unraid-cli.py           # Python CLI implementation
├── venv/                    # Python virtual environment
└── .claude/
    └── settings.local.json # Claude Code permissions

🔒 Safety Features

Data Protection

• ✅ Confirmation prompts for destructive operations
• ✅ .env in .gitignore prevents credential leaks
• ✅ Read-only by default - write operations require explicit flags
• ✅ No delete operations available in CLI (prevents accidents)

Container Management Safety

# Safe - requires confirmation
./unraid docker stop /plex
⚠️  Are you sure you want to stop container '/plex'? (yes/no):

# Skip confirmation for automation
./unraid docker stop --force /plex

Secure Credential Storage

# Good ✅
./unraid test

# Bad ❌ - Don't pass credentials on command line
UNRAID_API_KEY=secret ./unraid test

🏗️ Architecture

┌─────────────────────┐
│   Claude Desktop    │  ← AI Assistant with MCP
└──────────┬──────────┘
           │
           ├─────────────────────┐
           │                     │
    ┌──────▼──────┐      ┌──────▼──────┐
    │  Unraid MCP │      │ Hetzner MCP │
    │   Server    │      │   Server    │
    └──────┬──────┘      └──────┬──────┘
           │                     │
           ▼                     ▼
    ┌──────────────┐      ┌──────────────┐
    │    Unraid    │      │   Hetzner    │
    │    Server    │      │    Cloud     │
    └──────────────┘      └──────────────┘

┌─────────────────────┐
│    Claude Code      │  ← AI Assistant (CLI)
└──────────┬──────────┘
           │
           ├─────────────────────┐
           │                     │
    ┌──────▼──────┐      ┌──────▼──────┐
    │   ./unraid  │      │   hcloud    │
    │     CLI     │      │     CLI     │
    └──────┬──────┘      └──────┬──────┘
           │                     │
           ▼                     ▼
    ┌──────────────┐      ┌──────────────┐
    │    Unraid    │      │   Hetzner    │
    │  GraphQL API │      │     API      │
    └──────────────┘      └──────────────┘

Components

1. Unraid CLI (./unraid)

   • Custom Python CLI tool
   • Direct GraphQL API access
   • Safety confirmations built-in

2. Unraid MCP Server

   • Model Context Protocol server
   • 26 management tools
   • For Claude Desktop integration

3. Hetzner MCP Server

   • Official Hetzner Cloud MCP
   • Server and network management
   • SSH key handling

📚 Documentation

• Unraid CLI Guide - Comprehensive CLI documentation
• Claude Code Guide - Instructions for AI assistant
• Unraid API Docs - Official API reference
• Hetzner Cloud Docs - Official cloud docs

🤝 Use Cases

Home Lab Management

# Morning check
./unraid system && ./unraid array && ./unraid docker list

# Start media server
./unraid docker start /plex

# Monitor storage
./unraid array

Automation Scripts

#!/bin/bash
# backup-check.sh - Check if backup containers are running

CONTAINERS=$(./unraid docker list --json | jq -r '.docker.containers[] | select(.state == "RUNNING") | .names[0]')

if echo "$CONTAINERS" | grep -q "backup"; then
    echo "✅ Backup containers running"
else
    echo "❌ Backup containers not running!"
    ./unraid docker start /backup-container
fi

Infrastructure as Code

Use with Terraform, Ansible, or other IaC tools:

# Get current array capacity
CAPACITY=$(./unraid array --json | jq -r '.array.capacity.kilobytes.free')

# Provision new cloud resources if needed
if [ $CAPACITY -lt 1000000000 ]; then
    terraform apply -var="extra_storage=true"
fi

🛠️ Troubleshooting

Common Issues

Connection Refused

# Check if Unraid is accessible
curl -k https://homeserver.local

# Verify DNS resolution
ping homeserver.local

SSL Certificate Errors

# For self-signed certs, ensure this is set in .env:
UNRAID_VERIFY_SSL=false

Container Not Found

# List all containers to see exact names
./unraid docker list

# Container names include the / prefix
./unraid docker start /plex  # ✅ Correct
./unraid docker start plex   # ❌ Wrong

API Key Invalid

# Test connection
./unraid test

# Regenerate API key in Unraid WebUI
# Settings → Management Access → API Keys

Debug Mode

# Get detailed error messages
python3 unraid-cli.py system  # Direct Python execution

# Test GraphQL query manually
curl -k -s -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ info { os { hostname } } }"}' \
  https://homeserver.local/graphql

🔄 Updates

Update Unraid CLI

# Pull latest changes
git pull origin main

# Update dependencies
source venv/bin/activate
pip install --upgrade httpx python-dotenv

Update MCP Servers

# Update Unraid MCP
pipx upgrade unraid-mcp

# Update Hetzner MCP
pipx upgrade mcp-hetzner

🎯 Future Enhancements

Planned features:

• VM start/stop operations
• Parity check management
• User share operations
• Plugin management
• System shutdown/reboot
• Log streaming and viewing
• Notification management
• Backup automation

📄 License

This project is provided as-is for personal infrastructure management.

🙏 Acknowledgments

• Unraid MCP Server by @jmagar
• Hetzner Cloud for excellent cloud infrastructure
• Unraid for the powerful NAS OS
• Anthropic for Claude and Claude Code

📞 Support

• Unraid Issues: Unraid Forums
• Hetzner Issues: Hetzner Support
• This Tool: Use Claude Code for assistance!

---

Built with ❤️ using Claude Code

Last updated: November 2025