图统网站器器

Prerequisites

• 🚀 Bun (v1.0.26+) - Recommended
• 🏠 Home Assistant instance

Clone and install

git clone https://github.com/jango-blockchained/advanced-homeassistant-mcp.git cd advanced-homeassistant-mcp bun install

📦 Installation

Option 1: Smithery.ai (Recommended for Quick Setup)

Smithery is a registry for MCP servers that makes installation incredibly easy:

```bash

Install to Claude Desktop

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

Install to Cursor

npx @smithery/cli install @jango-blockchained/homeassistant-mcp --client cursor

Install Bun first if you don't have it

curl -fsSL https://bun.sh/install | bash

Option 4: Docker (Containerized)

Run the MCP server in a Docker container:

```bash

Or use docker-compose (see docker/ directory for examples)

```

Available Docker tags:

• latest - Latest stable release
• 1.6.0, 1.6, 1 - Tagged versions
• dev - Latest development build from main branch

Option 5: Local Installation

```bash

Install globally

bun add -g @jango-blockchained/homeassistant-mcp

Development Setup

bun install
bun run build
bun test

🚀 Quick Start

Get up and running in minutes:

```bash

Option 2: NPX (Quick Start)

npx @jango-blockchained/homeassistant-mcp@latest

🛠️ Usage

API Usage

Start the HTTP server:

bun run start -- --http

Available endpoints:

• POST /api/tools/call - Execute tools
• GET /api/resources/list - List resources
• GET /api/health - Health check
• WebSocket /api/ws - Real-time updates

🎯 Example Commands

Once integrated, your AI assistant can understand commands like:

Device Control:

"Turn off all lights in the bedroom" "Set the thermostat to 72°F" "Play music on the living room speaker" "Open the garage door" "Lock all doors" "Start the robot vacuum" "Set the bedroom fan to 50%"

Automation & Scenes:

"Activate the movie scene" "Trigger the morning routine automation" "Show me all my automations"

Information & Monitoring:

"What's the current temperature in the living room?" "Show me all unavailable devices" "Which lights are currently on?"

Notifications:

"Notify everyone that dinner is ready" "Send an alert to my phone"

Smart Maintenance:

"Check my Home Assistant health" "Find orphaned or unavailable devices" "Analyze my light usage patterns" "Show me my energy consumption" "Which devices have low battery?"

Aurora Sound-to-Light: ✨ NEW!

"Analyze this music file and sync my lights" "Scan for lights that can do Aurora effects" "Profile my living room lights for synchronization" "Create a light show for this song" "Play the timeline I just created" "Pause the light show" "Show me Aurora status"

Smart Scenarios:

"I'm leaving home, activate away mode" "Are any windows open with heating on?" "Check for energy-wasting issues" "Turn off everything, I'm going on vacation" "What can I do to save energy?"

You can also use prompts for guided assistance:

"Help me set up a morning routine" "Show me energy saving tips" "How do I control my media players?"

---

Configure environment

cp .env.example .env

Edit .env with your Home Assistant details

Option 3: Bunx with GitHub (No NPM Login Required)

If you can't login to npm, use Bunx to run directly from GitHub:

```bash

Run with environment variables

docker run -d \ -e HOME_ASSISTANT_URL=http://your-ha-instance:8123 \ -e HOME_ASSISTANT_TOKEN=your_long_lived_access_token \ -p 4000:4000 \ --name homeassistant-mcp \ ghcr.io/jango-blockchained/advanced-homeassistant-mcp:latest

Option 6: From Source (Most Flexible)

git clone https://github.com/jango-blockchained/advanced-homeassistant-mcp.git
cd advanced-homeassistant-mcp
bun install
bun run build
bun run start:stdio

---

Configuration

Create a .env file:

```env

AI Assistant Integration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bunx",
      "args": ["github:jango-blockchained/advanced-homeassistant-mcp"]
    }
  }
}

Or use npx:

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "npx",
      "args": ["@jango-blockchained/homeassistant-mcp@latest"]
    }
  }
}

VS Code + Copilot/Claude Extension

The .vscode/mcp.json is pre-configured for immediate use with the MCP extension. For development:

1. Ensure you have built the project: npm run build:stdio
2. Configure your environment variables in .env
3. The MCP server will automatically connect using the configuration in .vscode/mcp.json

Alternatively, you can manually configure in your VS Code settings:

{
  "mcp.servers": {
    "homeassistant-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/stdio-server.mjs"],
      "env": {
        "HASS_HOST": "${env:HASS_HOST}",
        "HASS_TOKEN": "${env:HASS_TOKEN}"
      }
    }
  }
}

Cursor

Add to .cursor/config/config.json:

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bunx",
      "args": ["github:jango-blockchained/advanced-homeassistant-mcp"]
    }
  }
}

Or with npx:

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "npx",
      "args": ["@jango-blockchained/homeassistant-mcp@latest"]
    }
  }
}

Core Components

• Transport Layer: HTTP, WebSocket, Stdio
• Middleware Layer: Security, validation, logging
• Tools Layer: Device control, automation, notifications
• Resource Manager: State management and caching

Install to VS Code

npx @smithery/cli install @jango-blockchained/homeassistant-mcp --client vscode ```

You'll be prompted to configure:

• Home Assistant URL
• Long-lived access token
• Optional settings (port, debug mode)

See the Smithery Deployment guide for details.