advanced-homeassistant

advanced-homeassistant is an MCP server that bridges AI assistants with Home Assistant, enabling natural language control over devices, scenes, automations, and more. It supports multiple transports (HTTP REST, WebSocket, and Standard I/O) and offers a modular plugin system for extensibility. You can run it locally via Bun, NPX, Bunx, or Docker, and connect it to clients like Claude Desktop, VS Code with Copilot/Claude, or Cursor. Once running, you can issue natural language commands (e.g., dim lights, adjust climate, trigger automations) and receive structured tool calls and real-time updates. The server emphasizes security with JWT authentication, rate limiting, and input sanitization, making it suitable for production use while handling complex home automation scenarios.

Prerequisites:

• Bun (v1.0.26+)
• A Home Assistant instance with a valid token (long-lived access token)

Option A: Quick Start (NPX)

• Install and run directly from GitHub: bunx github:jango-blockchained/advanced-homeassistant-mcp

Option B: Docker (containerized)

• Pull and run the latest image: docker pull ghcr.io/jango-blockchained/advanced-homeassistant-mcp:latest 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 C: Local installation (development)

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

Prerequisites recap:

• Bun installed and available in PATH
• Access to a Home Assistant instance with a long-lived token

Tips and common scenarios:

• Environment variables: set HASS_HOST and HASS_TOKEN to authorize Home Assistant requests. PORT and HOST control where the MCP server exposes its API. JWT_SECRET and rate-limiting settings are configurable for security.
• If using Smithery for deployment, you can install via the Smithery CLI with the usual commands shown in the README for this project.
• When testing, use the HTTP endpoint /api/tools/call to execute tools or /api/resources/list to inspect resources. Real-time updates come through WebSocket at /api/ws.
• For development, ensure you have built the project (bun run build:stdio) before starting the stdio server, and reference dist/stdio-server.mjs in your VS Code MCP configuration if you work with the editor integration.
• If you run into authentication issues, verify that JWT_SECRET is correctly configured and that the token you use from Home Assistant has appropriate permissions.