Godfrey2712/home_assistant

🚀 Setup Guide: Docker + Networking + Home Assistant

This guide explains how to install Docker, configure networking (Ethernet + Wi-Fi), and run Home Assistant on three different environments:

1. Ubuntu Laptop
2. Raspberry Pi (RPI)
3. Proxmox Server with VM

1️⃣ Ubuntu Laptop

Install Docker

# Update and install prerequisites
sudo apt update && sudo apt upgrade -y
sudo apt install -y ca-certificates curl gnupg lsb-release

# Add Docker’s official GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Add Docker repo
echo   "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu   $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Verify
docker --version

Add User to Docker Group

sudo usermod -aG docker $USER
newgrp docker

Run Home Assistant in Docker

docker run -d   --name homeassistant   --restart unless-stopped   --privileged   --network=host   -v ~/homeassistant:/config   ghcr.io/home-assistant/home-assistant:stable

Simple Run the start case in the homeassistant.sh file

./homeassistant.sh run

Access at: http://localhost:8123 or <pc_inet_address>:8123

2️⃣ Raspberry Pi (RPI)

Getting started

1. Ensure that an ubuntu os is the base os of the rpi. You can use a rpi imager to do this.
2. Get the IP of the rpi, either by connecting to a screen or connecting through an eth cable to a LAN and checking the IP Address from the WiFi.

Install Docker

# Update system
sudo apt update && sudo apt upgrade -y

# Install Docker using convenience script
curl -fsSL https://get.docker.com | sh

# Add user to Docker group
sudo usermod -aG docker $USER
newgrp docker

# Verify
docker --version

Configure Wi-Fi (Netplan)

Edit Netplan config (usually /etc/netplan/50-cloud-init.yaml):

network:
  version: 2
  ethernets:
    eth0:
      optional: true
      dhcp4: true
  wifis:
    wlan0:
      optional: true
      dhcp4: true
      access-points:
        "<your_wifi_name>":
          password: "<your_wifi_password>"
        "<your_wifi_name>":
          password: "<your_wifi_password>"

Apply:

sudo netplan apply

Check:

ip addr show wlan0

Run Home Assistant in Docker

docker run -d   --name homeassistant   --restart unless-stopped   --privileged   --network=host   -v /home/pi/homeassistant:/config   ghcr.io/home-assistant/home-assistant:stable

Simple Run the start case in the homeassistant.sh file

./homeassistant.sh run

Access at: http://<raspberrypi-ip>:8123 or homeassistant:8123

3️⃣ Proxmox Server with VM

VM Setup

• Use Ubuntu Server as VM OS.
• Configure Bridged networking so the VM gets its own LAN IP.

Install Docker (inside VM)

Follow the same steps as Ubuntu Laptop above.

Configure Networking (Optional Static IP)

Edit /etc/netplan/50-cloud-init.yaml:

network:
  version: 2
  ethernets:
    ens18:
      dhcp4: no
      addresses: [192.168.1.150/24]
      gateway4: 192.168.1.1
      nameservers:
        addresses: [8.8.8.8, 1.1.1.1]

Apply:

sudo netplan apply

Check:

ip addr show ens18

Run Home Assistant in Docker

docker run -d   --name homeassistant   --restart unless-stopped   --privileged   --network=host   -v ~/homeassistant:/config   ghcr.io/home-assistant/home-assistant:stable

Access at: http://<vm-ip>:8123

✅ Verification Checklist

• Docker test:

docker run hello-world

• Check IP addresses:

ip addr

• Access Home Assistant:
  • Ubuntu Laptop → http://localhost:8123
  • Raspberry Pi → http://<raspberrypi-ip>:8123
  • Proxmox VM → http://<vm-ip>:8123

🚀 Setup Guide: MCP Server for Claude, Cursor, and Custom Clients

This guide explains how to set up and run the MCP Server for integration with Claude Desktop, Cursor, and other custom clients. It also covers Docker setup, environment configuration, and troubleshooting.

📦 Requirements

• Docker installed (>= 20.x)
• .env file with the following variables:

HA_URL_LOCAL=
HA_URL_LAB=
HA_TOKEN_LOCAL=
HA_TOKEN_LAB=
PYTHONPATH=/app

⚠️ Keep your .env file private – do not commit it to GitHub.

🐳 Build & Run with Docker

1. Build the image

docker build -t mcp_server:latest .

2. Run the container

Use your .env file to inject environment variables into the container:

docker run -i --rm --network=host --env-file .env mcp_server:latest

Options explained:

• -i → interactive (MCP uses stdio for communication)
• --rm → auto-remove container when stopped
• --network=host → share host network (so http://localhost:8123 works directly)
• --env-file .env → loads secrets and configs from .env

▶️ Easy Start Script

For convenience, use the helper script:

/homeassistant.sh start-mcp

This wraps the build & run steps into a single command.

🐍 Python Environment Access

Inside your containerized MCP server, you can access environment variables directly:

import os

HA_URL = os.getenv("HA_URL_LOCAL")
HA_TOKEN = os.getenv("HA_TOKEN_LOCAL")

👉 Since Docker injects these variables, you don’t need load_dotenv() inside the container.

🔍 Debugging & Logs

If you need to check environment variables or connectivity inside the container:

1. Run the container in detached mode:

   docker run -d --name mcp_test --network=host --env-file .env mcp_server:latest
   

2. Open a shell inside the container:

   docker exec -it mcp_test /bin/bash
   

3. Print environment variables:

   env | grep HA_
   

4. Test connectivity to Home Assistant:

   curl -H "Authorization: Bearer $HA_TOKEN_LOCAL" "$HA_URL_LOCAL/api/"
   

5. Stop and remove the container:

   docker stop mcp_test && docker rm mcp_test
   

✅ Notes

• You don’t need to copy .env into the Docker image – it is passed at runtime via --env-file.
• If you want portability (image always contains .env), you can modify the Dockerfile to COPY .env .env, but it’s not recommended for security reasons.
• Keep .env files out of version control (.gitignore them).

🖥️ Using MCP Server with Claude Desktop or Cursor

To connect Claude Desktop or Cursor with your Home Assistant MCP server, configure the MCP client with the following JSON.

📄 MCP Config

{
  "mcpServers": {
    "Hass-MCP": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        "<FILE_PATH>/.env",
        "--network=host",
        "mcp_server:latest"
      ]
    }
  }
}