Home Assistant MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with the ability to interact with Home Assistant over WebSocket connections. This allows AI models to query device states, call services, fire events, and manage your smart home automation.

Features

• Real-time Home Assistant Integration: Connect to Home Assistant via WebSocket for live updates
• Device State Management: Query current states of all entities and devices
• Service Execution: Call Home Assistant services to control devices and automations
• Event System: Fire custom events to trigger automations or integrations
• Entity Discovery: List and filter entities by domain, device class, or search terms
• Service Discovery: Explore available services and their capabilities
• Connection Management: Automatic connection pooling and reconnection handling

Example prompts to try

Is anyone home right now?

How many devices are connected to my network?

Check the status of my house. Is there anything anomalous going on?

Prerequisites

• Home Assistant instance running (local or remote)
• Long-lived access token from Home Assistant
• Node.js 20+ installed

Example Claude Desktop Config

{
  "mcpServers": {
    "ha-mcp": {
      "command": "npx",
      "args": ["ha-mcp"],
      "env": {
        "HA_MCP_TOKEN": "<your home assistant token>",
        "HA_MCP_URL": "http://homeassistant.local:8123"
      }
    }
  }
}

Available Tools

Home Assistant

The main tool that provides all Home Assistant functionality:

Actions:

• get_states: Retrieve current states of entities
  • Optional filters: domain, device_class, q (search), limit
• get_state: Get state of a specific entity
  • Required: entity_id
• call_service: Execute a Home Assistant service
  • Required: domain, service
  • Optional: service_data, entity_id
• fire_event: Fire a custom event
  • Required: event_type
  • Optional: event_data
• list_entities: List available entities with filtering
  • Optional filters: domain, device_class, q (search), limit
• list_services: List available services by domain

Parameters:

• baseUrl: Home Assistant URL (default: http://homeassistant.local:8123) (or set HA_MCP_URL)
• token: Long-lived access token (or set HA_MCP_TOKEN env var)
• timezone: User timezone (default: America/Los Angeles) (or set HA_MCP_TIMEZONE)

Example Usage

Get all light entities:

{
  "action": "get_states",
  "listFilters": {
    "domain": "light",
    "limit": 50
  }
}

Turn on a light:

{
  "action": "call_service",
  "domain": "light",
  "service": "turn_on",
  "entity_id": "light.living_room",
  "service_data": {
    "brightness": 255,
    "color_temp": 4000
  }
}

Search for entities:

{
  "action": "list_entities",
  "listFilters": {
    "q": "temperature",
    "limit": 10
  }
}

Configuration

Environment Variables

• HA_MCP_TOKEN: Your Home Assistant long-lived access token
• HA_MCP_URL: Default Home Assistant URL (optional) (default: http://homeassistant.local:8123)
• HA_MCP_TIMEZONE: Your desired timezone (default: America/Los Angeles)

Transport Configuration

Stdio for now, a stand-alone http server may come soon.

Troubleshooting

Connection Issues

• Verify your Home Assistant URL is accessible
• Check that your long-lived access token is valid
• Ensure your Home Assistant instance allows external connections

Permission Errors

• Make sure your access token has the necessary permissions
• Check Home Assistant logs for authentication errors

Timeout Issues

• The server includes timeout protection (45s default)
• For large installations, consider using filters to limit results

License

Apache-2.0

Support

For issues and questions:

• Check the Home Assistant documentation