🏠 Home Assistant MCP

Talk to your house. Your AI assistant (Claude, GPT, Cursor, Copilot) — connected to Home Assistant through the Model Context Protocol. 40+ tools, three transports, one bunx command.

bash

# ⚡ Fastest way to try it
bunx github:jango-blockchained/advanced-homeassistant-mcp

---

🚀 Quick Start

You need a Home Assistant instance and a long-lived access token (create one here).

Claude Desktop

Add to claude_desktop_config.json:

json

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bunx",
      "args": ["github:jango-blockchained/advanced-homeassistant-mcp"],
      "env": {
        "HASS_HOST": "http://your-ha-instance:8123",
        "HASS_TOKEN": "your_long_lived_access_token"
      }
    }
  }
}

Restart Claude. You're done. Ask it to turn on the lights.

Cursor / VS Code

Cursor — add to .cursor/config/config.json

json

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "bunx",
      "args": ["github:jango-blockchained/advanced-homeassistant-mcp"],
      "env": {
        "HASS_HOST": "http://your-ha-instance:8123",
        "HASS_TOKEN": "your_long_lived_access_token"
      }
    }
  }
}

VS Code + MCP Extension

Set your env vars in a .env file and use the pre-configured .vscode/mcp.json:

json

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

Smithery (One-Click)

Install directly from the Smithery registry — no config files needed:

bash

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

---

📦 All Install Options

Method	Command
Smithery (easiest)	`npx @smithery/cli install @jango-blockchained/homeassistant-mcp --client claude`
bunx (no install)	`bunx github:jango-blockchained/advanced-homeassistant-mcp`
npx	`npx @jango-blockchained/homeassistant-mcp@latest`
Docker	`docker run -d -p 7123:7123 --env-file .env ghcr.io/jango-blockchained/advanced-homeassistant-mcp:1.6.1`
From source	`git clone ... && bun install && bun run build && bun run start:stdio`
npm global	`npm add -g @jango-blockchained/homeassistant-mcp && homeassistant-mcp`

Docker tags: latest, 1.6.1, 1.6, 1, dev

---

🎯 What You Can Do

Once connected, you talk to your house like you talk to a human:

code

"Turn off all lights in the bedroom"
"Set the thermostat to 72°F"
"Lock all doors and start the vacuum"
"Show me energy consumption this week"
"What's the temperature in the living room?"
"Activate the movie scene"
"Notify everyone that dinner is ready"
"Check my Home Assistant health"
"Find orphaned devices with low battery"
"Analyze my light usage patterns"

Every command maps to one of 40+ tools — lights, climate, media, locks, covers, fans, vacuums, alarms, scenes, automations, notifications, history, energy monitoring, maintenance, and more.

Full tool reference (all 41 tools)

Category	Tools
Lights	brightness, color temp, RGB, effects, turn on/off
Climate	HVAC modes, target temp, fan mode, humidify
Media	play/pause, volume, source, sound mode, shuffle
Covers	open/close, position, tilt, garage door
Locks	lock/unlock with code support
Fans	speed, oscillation, direction, preset
Vacuums	start/stop/dock, spot clean, fan speed
Alarm	arm home/away/night, disarm
Scenes	activate named scene
Automations	list, toggle, trigger, create/edit/delete
Notifications	push alerts via HA channels
History	query historical states
Add-ons	install, configure, control
Maintenance	orphaned devices, battery warnings, energy analysis
Smart Scenarios	nobody-home mode, window/heat conflicts, energy waste
Aurora	sound-to-light sync, BPM/beat detection, light shows
Speech	wake word detection, speech-to-text, voice commands

Full docs: Tools Reference

---

🎙️ Speech Features (Voice Control)

Transform your setup into a fully voice-controlled smart home assistant. The speech integration provides local, privacy-focused voice processing.

Wake Word Detection: Powered by wyoming-openwakeword (default: "Hey Jarvis").
Speech-to-Text: Fast, local transcription using faster-whisper.
Audio Integration: Direct PulseAudio integration for seamless microphone access.

To enable speech features, use the dedicated Docker Compose file:

bash

docker-compose -f docker-compose.speech.yml up -d

See the Speech Features Guide for detailed configuration and setup instructions.

---

🧱 Architecture

code

┌──────────────┐     ┌─────────────────────┐     ┌──────────────────┐
│  AI Assistant │◄───►│   Home Assistant    │◄───►│  Your Smart Home │
│ (Claude/GPT)  │     │    MCP Server       │     │  (Home Assistant)│
└──────────────┘     └─────────────────────┘     └──────────────────┘
                         │           │
                    ┌────┘           └────┐
                    ▼                     ▼
              ┌────────────┐      ┌──────────────┐
              │  HTTP/WS   │      │    STDIO     │
              │ (Express)  │      │ (fastmcp v3) │
              └────────────┘      └──────────────┘

Three transports, one codebase. Pick the one that fits your setup — all expose the same 40+ tools.

---

⚙️ Configuration

Minimal setup. Two variables are required:

env

HASS_HOST=http://homeassistant.local:8123
HASS_TOKEN=eyJ...                          # long-lived access token

Optional:

env

PORT=7123                                  # HTTP server port
LOG_LEVEL=info                             # debug | info | warn | error
JWT_SECRET=...                             # for HTTP/WS auth

---

🛠️ Development

bash

bun install              # install dependencies
bun run build:all        # build all three entry points
bun test                 # run test suite (80% coverage threshold)
bun run lint             # ESLint + Prettier

Built with Bun, TypeScript, and fastmcp. Three entry points:

dist/index.cjs — HTTP+WS on a custom Express-based MCP server
dist/stdio-server.mjs — STDIO via fastmcp v3
dist/http-server.mjs — HTTP via fastmcp v3

---

📖 Docs

Full documentation lives at **jango-blockchained.github.io/advanced-homeassistant-mcp** — covers installation, configuration, all 41 tools, deployment (HTTP, STDIO, Smithery), architecture deep-dives, and guides.

---

🤝 Contributing

PRs welcome. Keep it simple — same code style, add tests, update docs if you touch public APIs.

1. Fork it

2. Branch it

3. Code it

4. Test it

5. PR it

---

📄 License

MIT — go build something cool.

---

Your smart home speaks MCP. Now your AI speaks it too. 🏠⚡🤖🔋

Batteries included. 🔋

Advanced Homeassistant Mcp

Documentation

🏠 Home Assistant MCP

🚀 Quick Start

Claude Desktop

Cursor / VS Code

Smithery (One-Click)

📦 All Install Options

🎯 What You Can Do

🎙️ Speech Features (Voice Control)

🧱 Architecture

⚙️ Configuration

🛠️ Development

📖 Docs

🤝 Contributing

📄 License

Similar MCP

Mcp Open Library

Anilist Mcp

Metmuseum Mcp

Mcp Ipfs

Trending MCP

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare

Similar MCP

Mcp Open Library

Anilist Mcp

Metmuseum Mcp

Mcp Ipfs

Trending MCP

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare