by jango-blockchained
Enables AI assistants to control Home Assistant devices through natural language commands, offering secure authentication, rate limiting, and high‑performance streaming via the Bun runtime.
Home Assistant MCP provides a bridge that lets AI assistants such as Claude, GPT‑4, and Cursor interact with a Home Assistant instance. By translating natural‑language requests into Home Assistant API calls, it allows users to manage lights, climate, automations, notifications, and more without writing code.
npx @jango-blockchained/homeassistant-mcp@latest
Alternatively, use Docker, Bun, or Smithery as described in the README..env file (or set environment variables) with your Home Assistant URL and a long‑lived access token:
HASS_HOST=http://your-ha-instance:8123
HASS_TOKEN=your_long_lived_access_token
PORT=3000 # optional
JWT_SECRET=your_secret # optional
bun run start -- --http
Q: Do I need Node.js?
A: No. The server runs on Bun, which includes its own JavaScript engine. If you prefer Node, you can still run the package via npx, but Bun is recommended for performance.
Q: How is authentication handled?
A: The server expects a Home Assistant long‑lived access token (HASS_TOKEN) and optionally a JWT secret for client‑side authentication. Rate limiting and input sanitisation are enforced automatically.
Q: Can I use the server behind a reverse proxy? A: Yes. Expose the HTTP/WebSocket ports (default 3000) and configure your proxy to forward them. Security headers are added by the server, but you may add additional TLS termination at the proxy.
Q: Are there any OS restrictions? A: Bun supports Linux, macOS, and Windows. Docker images are provided for any platform that can run containers.
Q: How do I add custom tools?
A: Create a new module in the tools directory and register it in the server’s configuration. The modular architecture allows hot‑reloading without restarting the whole service.
Q: What is the recommended way to keep the server up‑to‑date?
A: Use the automated GitHub Actions workflow that bumps the version, publishes to npm, and pushes a new Docker image. You can also run npx @jango-blockchained/homeassistant-mcp@latest to fetch the latest release.
Bridge the gap between AI assistants and your smart home 🚀
A powerful, secure, and extensible Model Context Protocol (MCP) server that enables AI assistants like Claude, GPT, and Cursor to seamlessly interact with Home Assistant. Control your lights, climate, automations, and more through natural language commands.
Get up and running in minutes:
# Clone and install
git clone https://github.com/jango-blockchained/advanced-homeassistant-mcp.git
cd advanced-homeassistant-mcp
bun install
# Configure environment
cp .env.example .env
# Edit .env with your Home Assistant details
# Start the server
bun run start:stdio
That's it! Your AI assistant can now control your smart home. 🤖✨
Smithery is a registry for MCP servers that makes installation incredibly easy:
# 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 to VS Code
npx @smithery/cli install @jango-blockchained/homeassistant-mcp --client vscode
You'll be prompted to configure:
See SMITHERY_DEPLOYMENT.md for detailed deployment guide.
npx @jango-blockchained/homeassistant-mcp@latest
If you can't login to npm, use Bunx to run directly from GitHub:
# Install Bun first if you don't have it
curl -fsSL https://bun.sh/install | bash
# Then run from GitHub
bunx github:jango-blockchained/advanced-homeassistant-mcp
Alternatively, install directly from Git:
bun add git+https://github.com/jango-blockchained/advanced-homeassistant-mcp.git
homeassistant-mcp
Run the MCP server in a Docker container:
# Pull the latest image
docker pull ghcr.io/jango-blockchained/advanced-homeassistant-mcp:latest
# 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
# Or use docker-compose (see docker/ directory for examples)
Available Docker tags:
latest - Latest stable release1.0.x - Specific versiondev - Latest development build from main branch# Install globally
bun add -g @jango-blockchained/homeassistant-mcp
# Or locally
bun add homeassistant-mcp
# Run
homeassistant-mcp
git clone https://github.com/jango-blockchained/advanced-homeassistant-mcp.git
cd advanced-homeassistant-mcp
bun install
bun run build
bun run start:stdio
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"]
}
}
}
The .vscode/settings.json is pre-configured for immediate use.
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"]
}
}
}
Start the HTTP server:
bun run start -- --http
Available endpoints:
POST /api/tools/call - Execute toolsGET /api/resources/list - List resourcesGET /api/health - Health checkWebSocket /api/ws - Real-time updatesCreate a .env file:
# Home Assistant
HASS_HOST=http://your-ha-instance:8123
HASS_TOKEN=your_long_lived_access_token
# Server
PORT=3000
NODE_ENV=production
# Security
JWT_SECRET=your-secret-key
RATE_LIMIT_WINDOW=15
RATE_LIMIT_MAX=50
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ AI Assistant │◄──►│ MCP Server │◄──►│ Home Assistant │
│ (Claude/GPT) │ │ │ │ │
└─────────────────┘ │ ┌─────────────┐ │ └─────────────────┘
│ │ Transport │ │
│ │ Layer │ │
│ └─────────────┘ │
│ ┌─────────────┐ │
│ │ Middleware │ │
│ │ Layer │ │
│ └─────────────┘ │
│ ┌─────────────┐ │
│ │ Tools │ │
│ │ Layer │ │
└─────────────────┘
🎨 Aurora is a complete sound-to-light synchronization system that transforms your Home Assistant lights into a professional light show synchronized to music!
🔧 Maintenance Tool: Spook-like maintenance features
🧠 Smart Scenarios: Intelligent automation detection
📖 See Complete Tools Reference for detailed documentation
📝 Prompts: Pre-defined prompt templates for common home automation tasks
📊 Resources: Direct access to Home Assistant states and configurations
🛠️ 24 Comprehensive Tools: Full device control and smart automation
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?"
We welcome contributions! Here's how to get involved:
bun install
bun run build
bun test
This project uses automated releases to GitHub, npm, and Docker. See AUTOMATED_RELEASES.md for details.
Quick Release:
MIT License - see LICENSE for details.
Built with ❤️ using:
Transform your smart home into an AI-powered experience
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by activepieces
A self‑hosted, open‑source platform that provides a no‑code builder for creating, versioning, and running AI‑driven automation workflows. Pieces are TypeScript‑based plugins that become MCP servers, allowing direct consumption by large language models.
by Skyvern-AI
Automates browser‑based workflows by leveraging large language models and computer‑vision techniques, turning natural‑language prompts into fully functional web interactions without writing custom scripts.
by ahujasid
Enables Claude AI to control Blender for prompt‑assisted 3D modeling, scene creation, and manipulation via a socket‑based Model Context Protocol server.
by PipedreamHQ
Connect APIs quickly with a free, hosted integration platform that enables event‑driven automations across 1,000+ services and supports custom code in Node.js, Python, Go, or Bash.
by elie222
Organizes email inbox, drafts replies in the user's tone, tracks follow‑ups, and provides analytics to achieve inbox zero quickly.
by grab
Enables Cursor AI to read and programmatically modify Figma designs through a Model Context Protocol integration.
by CursorTouch
Enables AI agents to control the Windows operating system, performing file navigation, application launching, UI interaction, QA testing, and other automation tasks through a lightweight server.
by ahujasid
Enables Claude AI to control Ableton Live in real time, allowing AI‑driven creation, editing, and playback of tracks, clips, instruments, and effects through a socket‑based server.
by leonardsellem
Provides tools and resources to enable AI assistants to manage and execute n8n workflows via natural language commands.
{
"mcpServers": {
"homeassistant-mcp": {
"command": "npx",
"args": [
"-y",
"@jango-blockchained/homeassistant-mcp"
],
"env": {
"HASS_HOST": "<HOME_ASSISTANT_URL>",
"HASS_TOKEN": "<HOME_ASSISTANT_LONG_LIVED_ACCESS_TOKEN>"
}
}
}
}claude mcp add homeassistant-mcp npx -y @jango-blockchained/homeassistant-mcp