Home Assistant Integration MCP Server

Smart HomeTypeScript

Control and monitor your Home Assistant smart home devices through Claude

Available Tools

getDevices

Retrieves a list of all available devices from Home Assistant

getDeviceState

Gets the current state of a specific device

controlDevice

Controls a device by calling a service (turn on/off, set temperature, etc.)

callService

Calls any Home Assistant service with specified domain, service, and data

subscribeToEvents

Subscribes to real-time state change events from Home Assistant

Home Assistant Integration provides a seamless connection between Claude AI and your Home Assistant smart home ecosystem. This integration allows you to control lights, switches, thermostats, media players, and other smart devices directly through Claude's interface. With real-time state updates via Server-Sent Events (SSE), you can monitor device status changes and create powerful automation workflows combining Claude's intelligence with your smart home capabilities.

Home Assistant Integration for Claude

This MCP server connects Claude to your Home Assistant instance, allowing you to control and monitor your smart home devices through natural language conversations.

Prerequisites

Node.js v20.10.0 or higher
A running Home Assistant instance
Home Assistant Long-Lived Access Token

Installation

Option 1: Manual Setup

Clone the repository:

git clone https://github.com/tevonsb/homeassistant-mcp.git
cd homeassistant-mcp

Install dependencies:
```
npm install
```

Create a .env file based on the example:

NODE_ENV=development
PORT=3000
LOG_LEVEL=info
HASS_HOST=http://your-home-assistant-url:8123
HASS_SOCKET_URL=ws://your-home-assistant-url:8123/api/websocket
HASS_TOKEN=your_long_lived_access_token

Start the server:
```
npm start
```

Option 2: Docker Setup

Build the Docker image:
```
docker build -t homeassistant-mcp .
```

Run the container:

docker run -p 3000:3000 \
  -e HASS_HOST=http://your-home-assistant-url:8123 \
  -e HASS_SOCKET_URL=ws://your-home-assistant-url:8123/api/websocket \
  -e HASS_TOKEN=your_long_lived_access_token \
  homeassistant-mcp

Option 3: macOS Quick Setup

For macOS users, a convenient setup script is provided:

chmod +x claude-desktop-macos-setup.sh
./claude-desktop-macos-setup.sh

This script will guide you through the installation process, including Node.js setup and configuration.

Configuration

To use this MCP with Claude, you need to add it to your Claude configuration. In Claude Desktop, go to Settings > Model Context Protocol and add the following configuration:

{
  "homeassistant": {
    "command": "node",
    "args": [
      "/path/to/homeassistant-mcp/dist/index.js"
    ],
    "env": {
      "HASS_HOST": "http://your-home-assistant-url:8123",
      "HASS_SOCKET_URL": "ws://your-home-assistant-url:8123/api/websocket",
      "HASS_TOKEN": "your_long_lived_access_token"
    }
  }
}

Usage

Once configured, you can interact with your Home Assistant devices through Claude using natural language. Here are some examples:

"Turn on the living room lights"
"What's the current temperature in the bedroom?"
"Set the thermostat to 72 degrees"
"Is my front door locked?"
"Show me all the lights that are currently on"
"Play music on the living room speaker"

The integration supports various device types including:

Lights
Switches
Climate devices (thermostats)
Sensors
Media players
Locks
Cameras
Scenes
Scripts
Fans
Vacuums

Real-time Updates

The MCP server supports Server-Sent Events (SSE) for real-time updates from your Home Assistant instance. This allows Claude to receive notifications when device states change without having to poll for updates.

Troubleshooting

If you encounter issues:

Check your Home Assistant connection and token validity
Verify your environment variables are correctly set
Check the server logs for detailed error messages
Ensure your Home Assistant instance is accessible from the machine running the MCP server

For Docker users, you may need to use the host network mode if your Home Assistant instance is running on the same machine:

docker run --network host \
  -e HASS_HOST=http://localhost:8123 \
  -e HASS_SOCKET_URL=ws://localhost:8123/api/websocket \
  -e HASS_TOKEN=your_long_lived_access_token \
  homeassistant-mcp