🏡 Home Assistant MCP (Model Context Protocol) 🚀

The AI-powered bridge between you and your smart home.
Control, monitor, and automate your Home Assistant and Node-RED setup using natural language and powerful tools—right from your favorite AI assistant!

---

✨ Features at a Glance

• 🤖 AI-Driven Automations: List, create, update, and delete automations with ease.
• 💡 Entity Control: Manage lights, switches, sensors, and more—individually or in bulk.
• 🎵 Media Player Magic: Play, pause, adjust volume, and control your home's soundscape.
• 🔄 Real-Time Updates: Get instant feedback and event-driven automations via WebSocket.
• 🛠️ Node-RED Integration: Full flow management and deployment.
• 🖥️ Dashboard Management: API and YAML-based Lovelace dashboard tools.
• 🧩 Modular & Extensible: Add new tools, domains, and integrations with minimal effort.
• 🔒 Secure by Design: Token-based authentication and environment-based configuration.
• 🧪 Battle-Tested: All tests pass after every refactor!

---

🚀 Quick Start

1️⃣ With Cursor MCP

git clone https://github.com/yourusername/home-assistant-mcp.git
cd home-assistant-mcp
npm install
npm run build

Create .cursor/mcp.json:

{
  "mcpServers": {
    "home-assistant": {
      "command": "node",
      "args": ["<path/to/your/dist/folder>"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "your_long_lived_access_token",
        "HA_WEBSOCKET_URL": "ws://homeassistant.local:8123/api/websocket",
        "NODE_RED_URL": "http://homeassistant.local:1880",
        "NODE_RED_USERNAME": "your_node_red_username",
        "NODE_RED_PASSWORD": "your_node_red_password"
      }
    }
  }
}

💡 Tip: Open Cursor's chat and try:
"List all my Home Assistant automations"

---

2️⃣ Standalone Mode

git clone https://github.com/yourusername/home-assistant-mcp.git
cd home-assistant-mcp
npm install

Create a .env file:

HA_URL=http://homeassistant.local:8123
HA_TOKEN=your_long_lived_access_token
HA_WEBSOCKET_URL=ws://homeassistant.local:8123/api/websocket
NODE_RED_URL=http://homeassistant.local:1880
NODE_RED_USERNAME=your_node_red_username
NODE_RED_PASSWORD=your_node_red_password

Build and start:

npm run build
npm start

---

🧑‍💻 Development

• Hot reload: npm run dev
• Run tests: npm test
• Lint: npm run lint
• Format: npm run format

✅ All tests pass after every refactor!

---

🛠️ Tool Reference & Examples

Automations

• List automations:
  "Show me all automations"
• Create automation:
  "Create an automation to turn on the living room light at sunset"

Entities

• List entities:
  "List all lights"
• Update entity:
  "Turn off the kitchen light"

Media Players

• Control playback:
  "Pause the living room TV"
• Set volume:
  "Set the bedroom speaker to 50%"

Node-RED

• List flows:
  "Show all Node-RED flows"
• Deploy flows:
  "Deploy Node-RED flows"

Dashboards

• List dashboards:
  "List all Lovelace dashboards"
• Update dashboard:
  "Update the main dashboard to add a new card"

---

🤖 More LLM Prompt Examples

• 🏠 Home Control:

  • "Dim the living room lights to 30% at 8pm every night."
  • "What sensors are currently open?"
  • "Turn off all lights in the house."
  • "Is the garage door open?"

• 🔔 Automations & Scheduling:

  • "Create an automation to notify me if the front door is left open for more than 5 minutes."
  • "Disable the 'Good Night' automation until tomorrow."
  • "List automations that control the kitchen lights."

• 🎶 Media & Entertainment:

  • "Play jazz on the living room speakers."
  • "Mute all media players."
  • "What is currently playing in the bedroom?"

• 🧑‍🔧 Node-RED & Advanced Flows:

  • "Show me all Node-RED flows that use the 'motion detected' event."
  • "Update the 'morning routine' flow to include weather forecast."

• 🖥️ Dashboards & UI:

  • "Add a weather card to the main dashboard."
  • "Remove the 'energy usage' card from the overview dashboard."

• 🎭 Scenes & Themes:

  • "Activate the 'Movie Night' scene."
  • "Switch to dark theme at sunset automatically."

• 🔄 Updates & Maintenance:

  • "Check for Home Assistant updates."
  • "Update all add-ons to the latest version."

• 🛠️ Troubleshooting & Info:

  • "Why did the 'morning lights' automation fail?"
  • "Show me the last 10 log entries for the thermostat."
  • "Validate my Home Assistant configuration."

• 📦 MQTT & Integrations:

  • "Publish 'ON' to topic 'home/garden/lights'."
  • "Subscribe to MQTT topic 'home/alerts'."

• 🕹️ Custom Services:

  • "Call the 'vacuum.start' service for the living room vacuum."
  • "Restart Home Assistant core."

---

🏗️ Architectural Patterns

• 🧩 Modular, domain-driven tool architecture
• 🔌 REST & WebSocket separation
• 🗃️ Explicit tool registration in src/index.ts
• 🛡️ Strong typing & validation
• 🕹️ Observer/EventEmitter for real-time events
• 🏭 Factory & strategy for tool creation
• 🦾 Singleton WebSocket client
• 🧪 Comprehensive error handling & automated testing

---

🗂️ Project Structure

src/
  config/         # Configuration logic
  tools/          # All tool implementations (REST & WebSocket)
  types/          # TypeScript type definitions
  utils/          # API & WebSocket utilities
  index.ts        # Explicit tool registration
dist/             # Compiled output

---

🔐 Security

• Keep your Home Assistant token safe!
• Use a restricted user for the access token.
• All WebSocket connections are authenticated.

---

🆘 Troubleshooting

• Node.js error?
  Use Node.js v20.10.0+ (nvm install 20.10.0)
• Connection issues?
  Check your Home Assistant and Node-RED URLs and tokens.
• Test failures?
  Run npm test and review the output.

---

📝 License

MIT

---

⭐️ Contributing

1. Fork the repo
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass (npm test)
5. Submit a pull request!

---

💬 Example Usage

# List all automations
curl -X GET http://localhost:3000/api/automations -H 'Authorization: ApiKey <your_token>'

# Turn on a light
curl -X POST http://localhost:3000/api/action \\
  -H 'Authorization: ApiKey <your_token>' \\
  -H 'Content-Type: application/json' \\
  -d '{"action": "turn_on_lights", "parameters": {"room": "living_room"}}'

---

📎 Resources

• Home Assistant Docs
• Node-RED Docs
• Project GitHub