hass_mcp

FlorentB974/hass_mcp

3.2

If you are the rightful owner of hass_mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A comprehensive Model Context Protocol (MCP) server for Home Assistant integration with Server-Sent Events (SSE) support.

Tools
5
Resources
0
Prompts
0

Home Assistant MCP Server with SSE Support

A comprehensive Model Context Protocol (MCP) server for Home Assistant integration with Server-Sent Events (SSE) support. This server enables AI applications to interact with Home Assistant entities including lights, garage doors, smart locks, solar inverters, sensors, and more.

Features

šŸ  Home Assistant Integration

  • Complete Entity Control: Manage all types of Home Assistant entities
  • Real-time State Updates: Get live updates via Server-Sent Events (SSE)
  • Smart Device Support: Control lights, switches, covers, locks, sensors, and more
  • Advanced Light Control: Brightness, color temperature, RGB color control
  • Sensor Data Access: Temperature, humidity, energy consumption, solar inverter data

šŸ”§ MCP Tools

  • get_all_entities - Discover and list all entities, filter by domain or area
  • control_light - Full light control with brightness and color options
  • control_switch - Control switches, garage doors, smart locks, and binary devices
  • get_entity_state - Get detailed state and attributes of specific entities
  • get_sensor_data - Access sensor data including solar inverters and energy monitoring

šŸ“Š MCP Resources

  • homeassistant://entities - Complete entity list with states and attributes
  • homeassistant://config - Home Assistant configuration and system information

šŸŒŠ Server-Sent Events (SSE)

Real-time event streaming on port 3001:

  • Entity Updates: Live entity state changes
  • Device Control Events: Real-time feedback from device operations
  • Sensor Data: Continuous sensor data streaming
  • Heartbeat: Connection health monitoring

Installation & Setup

Prerequisites

  • Node.js 18+
  • TypeScript
  • Home Assistant instance with API access
  • Home Assistant Long-Lived Access Token

1. Install Dependencies

npm install

2. Build the Project

npm run build

3. Configure Environment Variables

Create a .env file or set environment variables:

# Required: Home Assistant API access
export HASS_ACCESS_TOKEN="your_long_lived_access_token"
export HASS_BASE_URL="http://your-homeassistant:8123"

# Optional: SSE server configuration  
export SSE_PORT="3001"
export HASS_WEBSOCKET_URL="ws://your-homeassistant:8123/api/websocket"

4. Get Home Assistant Access Token

  1. Go to your Home Assistant Profile ā†’ Security tab
  2. Create a Long-Lived Access Token
  3. Copy the token and set it as HASS_ACCESS_TOKEN

Usage

Running the MCP Server

npm start

Running with Custom Environment

HASS_ACCESS_TOKEN="your_token" HASS_BASE_URL="http://192.168.1.100:8123" npm start

Testing the Server

# Test the MCP server
npm test

# Check SSE endpoint
curl http://localhost:3001/health

# Monitor SSE stream
curl -N http://localhost:3001/events

MCP Client Configuration

For Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "home-assistant": {
      "command": "node",
      "args": ["/absolute/path/to/hass_mcp/build/index.js"],
      "env": {
        "HASS_ACCESS_TOKEN": "your_long_lived_access_token",
        "HASS_BASE_URL": "http://your-homeassistant:8123"
      }
    }
  }
}

For VS Code MCP

Use the provided .vscode/mcp.json configuration file.

API Examples

Entity Discovery

# Get all lights
Tool: get_all_entities
Args: {"domain": "light"}

# Get living room devices  
Tool: get_all_entities
Args: {"area": "living room"}

Light Control

# Turn on light with brightness
Tool: control_light
Args: {
  "entity_id": "light.living_room", 
  "action": "turn_on", 
  "brightness": 128
}

# Set light color
Tool: control_light
Args: {
  "entity_id": "light.bedroom",
  "action": "turn_on",
  "rgb_color": [255, 0, 0]
}

Device Control

# Open garage door
Tool: control_switch
Args: {"entity_id": "cover.garage_door", "action": "turn_on"}

# Lock smart lock
Tool: control_switch  
Args: {"entity_id": "lock.front_door", "action": "turn_off"}

Sensor Data

# Get solar inverter data
Tool: get_sensor_data
Args: {"sensor_type": "solar"}

# Get energy consumption
Tool: get_sensor_data
Args: {"sensor_type": "energy"}

Server-Sent Events (SSE)

Connecting to SSE Stream

const eventSource = new EventSource('http://localhost:3001/events');

eventSource.onmessage = function(event) {
    const data = JSON.parse(event.data);
    console.log('Event:', data);
};

// Listen for specific events
eventSource.addEventListener('light_controlled', function(event) {
    const data = JSON.parse(event.data);
    console.log('Light changed:', data);
});

SSE Event Types

  • connected - Initial connection established
  • entities_updated - Entity list updated
  • light_controlled - Light state changed
  • device_controlled - Device state changed
  • sensor_data_fetched - Sensor data retrieved
  • heartbeat - Keep-alive signal (every 30s)

Supported Device Types

Lights (light.*)

  • On/off control
  • Brightness adjustment (0-255)
  • Color temperature control
  • RGB color control
  • State monitoring

Switches (switch.*)

  • On/off control
  • State monitoring

Covers (cover.*)

  • Open/close control (garage doors, blinds, etc.)
  • Position control
  • State monitoring

Locks (lock.*)

  • Lock/unlock control
  • State monitoring

Sensors (sensor.*)

  • Temperature sensors
  • Humidity sensors
  • Energy monitoring
  • Solar inverter data
  • Motion sensors
  • And more...

Security Considerations

  • Use Home Assistant Long-Lived Access Tokens
  • Restrict network access to trusted clients
  • Monitor SSE connections and events
  • Regularly rotate access tokens
  • Use HTTPS in production environments

Troubleshooting

Common Issues

Connection Failed

# Check Home Assistant API accessibility
curl -H "Authorization: Bearer YOUR_TOKEN" http://your-homeassistant:8123/api/states

# Verify token permissions
curl -H "Authorization: Bearer YOUR_TOKEN" http://your-homeassistant:8123/api/config

SSE Not Working

  • Check if port 3001 is available
  • Verify CORS settings
  • Check firewall rules

Entity Not Found

  • Verify entity ID format: domain.entity_name
  • Check entity exists in Home Assistant
  • Ensure entity is enabled

Debug Mode

# Enable debug logging
DEBUG=mcp:* npm start

# Check health endpoint
curl http://localhost:3001/health

Development

Project Structure

src/
ā”œā”€ā”€ index.ts              # Main MCP server implementation
ā”œā”€ā”€ types/               # TypeScript type definitions  
ā””ā”€ā”€ utils/               # Utility functions

build/                   # Compiled JavaScript output
.vscode/mcp.json        # VS Code MCP configuration
package.json            # Dependencies and scripts
tsconfig.json           # TypeScript configuration

Building from Source

git clone <repository>
cd hass_mcp
npm install
npm run build

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

  • Check Home Assistant API documentation
  • Review MCP protocol specification
  • Open GitHub issues for bugs
  • Join community discussions

Built with ā¤ļø for the Home Assistant and MCP communities