Installation Guide 🛠️

This guide covers different methods to install and set up the MCP Server for Home Assistant. Choose the installation method that best suits your needs.

Prerequisites

Before installing MCP Server, ensure you have:

Home Assistant instance running and accessible
Node.js 18+ or Docker installed
Home Assistant Long-Lived Access Token (How to get one)

Installation Methods

1. 🔧 Smithery Installation (Recommended)

The easiest way to install MCP Server is through Smithery:

Smithery Configuration

The project includes a smithery.yaml configuration:

# Add smithery.yaml contents and explanation

Installation Steps

npx -y @smithery/cli install @jango-blockchained/advanced-homeassistant-mcp --client claude

2. 🐳 Docker Installation

For a containerized deployment:

# Clone the repository
git clone --depth 1 https://github.com/jango-blockchained/advanced-homeassistant-mcp.git
cd advanced-homeassistant-mcp

# Configure environment variables
cp .env.example .env
# Edit .env with your Home Assistant details:
# - HA_URL: Your Home Assistant URL
# - HA_TOKEN: Your Long-Lived Access Token
# - Other configuration options

# Build and start containers
docker compose up -d --build

# View logs (optional)
docker compose logs -f --tail=50

3. 💻 Manual Installation

For direct installation on your system:

# Install Bun runtime
curl -fsSL https://bun.sh/install | bash

# Clone and install
git clone https://github.com/jango-blockchained/advanced-homeassistant-mcp.git
cd advanced-homeassistant-mcp
bun install --frozen-lockfile

# Configure environment
cp .env.example .env
# Edit .env with your configuration

# Start the server
bun run dev --watch

Configuration

Environment Variables

Key configuration options in your .env file:

# Home Assistant Configuration
HA_URL=http://your-homeassistant:8123
HA_TOKEN=your_long_lived_access_token

# Server Configuration
PORT=3000
HOST=0.0.0.0
NODE_ENV=production

# Security Settings
JWT_SECRET=your_secure_jwt_secret
RATE_LIMIT=100

Client Integration

Cursor Integration

Add to .cursor/config/config.json:

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bun",
      "args": ["run", "start"],
      "cwd": "${workspaceRoot}",
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}

Claude Desktop Integration

Add to your Claude configuration:

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bun",
      "args": ["run", "start", "--port", "8080"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Verification

To verify your installation:

Check server status:
```
curl http://localhost:3000/health
```
Test Home Assistant connection:
```
curl http://localhost:3000/api/state
```

Troubleshooting

If you encounter issues:

Check the Troubleshooting Guide
Verify your environment variables

Check server logs:

# For Docker installation
docker compose logs -f

# For manual installation
bun run dev

Next Steps

Follow the Quick Start Guide to begin using MCP Server
Read the API Documentation for integration details
Check the Architecture Overview to understand the system

Support

Need help? Check our Support Resources or open an issue.