What is Home Assistant Mcp

home-assistant-mcp is an integration that connects Anthropic’s Claude with Home Assistant, enabling users to control and interact with their home automation system using natural language commands.

Use cases

Use cases for home-assistant-mcp include controlling smart lights and appliances via voice commands, managing home entertainment systems, automating tasks based on user preferences, and integrating with Node-RED for advanced automation workflows.

How to use

To use home-assistant-mcp, install the package in your Home Assistant environment, configure the necessary API settings, and obtain a long-lived access token. Once set up, you can use natural language to manage automations, control entities, and interact with media players.

Key features

Key features of home-assistant-mcp include automation management (create, update, delete automations), entity control (list and update entities), media player control (playback and volume management), updates management (check and simulate updates), and Node-RED integration (manage flows).

Where to use

home-assistant-mcp can be used in smart home environments, allowing users to enhance their home automation experience through natural language processing, making it suitable for residential and commercial applications.

🏡 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