home / mcp / enhanced home assistant mcp server

Enhanced Home Assistant MCP Server

Enhanced MCP server for Home Assistant with comprehensive API integration - includes entity discovery, automation management, advanced services, system monitoring, and more

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "gilberth-enhanced-homeassistant-mcp": {
      "command": "npx",
      "args": [
        "@thelord/enhanced-homeassistant-mcp"
      ],
      "env": {
        "HOME_ASSISTANT_URL": "http://your-ha-url:8123",
        "HOME_ASSISTANT_TOKEN": "your_long_lived_access_token"
      }
    }
  }
}

You run a practical MCP server that bridges Home Assistant with AI assistants, letting you query entity states, trigger automations, manage devices, and oversee system health from your preferred client. This guide shows you how to use the Enhanced Home Assistant MCP server, install it, and configure it for reliable operations with your Home Assistant instance.

How to use

You use an MCP client to communicate with the Enhanced Home Assistant MCP server. Start the server with the NPX command provided, then connect your MCP client to its runtime. From the client you can check API status, get and set entity states, call services, manage automations, scenes, scripts, and access history and logs. You provide your Home Assistant URL and a long-lived access token to authorize requests. When connected, you can discover entities, monitor system health, and trigger actions across lights, climate, media players, covers, and notifications.

To begin, run the server in your terminal and then use your MCP client to send actions such as querying an entity state, turning on a light with brightness and color, triggering an automation, or activating a scene. The server exposes a broad set of tools organized into categories like Basic Operations, Automation & Control, History & Monitoring, Device Control, and System Administration to help you perform common Home Assistant tasks from your AI-enabled interface.

How to install

Prerequisites: Make sure you have Node.js 18 or newer installed on your machine. You also need a Home Assistant instance with API access and a long-lived access token.

# Prerequisites check
node -v
npm -v

# Optional: use a local clone or simply run with NPX

Step-by-step installation flow you can follow exactly as shown here:

# Clone the repository
git clone https://github.com/gilberth/enhanced-homeassistant-mcp.git
cd enhanced-homeassistant-mcp

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

Configure your environment by editing the .env file to include your Home Assistant details.

HOME_ASSISTANT_URL=http://homeassistant.local:8123
HOME_ASSISTANT_TOKEN=your_long_lived_access_token_here
DEBUG=false
REQUEST_TIMEOUT=10000

Set up your access token in Home Assistant by generating a Long-Lived Access Token from your profile.

Running the server can be done via NPX for a quick start or via a local installation for production use.

# Quick start with NPX
npx @thelord/enhanced-homeassistant-mcp

# With options
npx @thelord/enhanced-homeassistant-mcp --debug start
npx @thelord/enhanced-homeassistant-mcp inspect
npx @thelord/enhanced-homeassistant-mcp health

Additional content

Security and reliability tips: keep your Home Assistant token secure, rotate tokens periodically, and enable debug logging during troubleshooting to capture useful diagnostics. If you plan to run the server in production, consider using a process manager to keep the MCP server running and to restart it on crashes.

Notes on deployment patterns: you can run the MCP server locally via NPX for development or build a dedicated container image for deployment. If you want to run in the cloud, you can use Smithery to provision and manage the MCP server instance with your Home Assistant credentials.

Troubleshooting quick tips: verify the HOME_ASSISTANT_URL and HOME_ASSISTANT_TOKEN are correct, ensure Home Assistant is reachable from your network, and confirm your token has the required permissions for the actions you intend to perform. If a specific action fails, list all available services and entities to confirm you are using valid identifiers.

Notes on usage patterns

Typical workflows include querying entity states before issuing a control command, validating the available services, and using history or log events to inform your automation logic. Use the discovery features to find devices by type or domain, then combine multiple tools to create robust automation sequences.

Available tools

homeassistant_api_status

Check API connectivity between MCP server and Home Assistant instance

homeassistant_get_entity_state

Retrieve the current state of a specific entity from Home Assistant

homeassistant_list_all_entities

List all entities available in Home Assistant, optionally filtered by domain

homeassistant_call_service

Invoke a Home Assistant service with domain, service, entity_id, and service_data parameters

homeassistant_list_services

List available Home Assistant services, optionally filtered by domain

homeassistant_get_config

Fetch Home Assistant configuration details

homeassistant_list_automations

List automations defined in Home Assistant

homeassistant_toggle_automation

Enable or disable a specific automation by entity_id

homeassistant_trigger_automation

Trigger a Home Assistant automation by entity_id

homeassistant_list_scenes

List all scenes defined in Home Assistant

homeassistant_activate_scene

Activate a Home Assistant scene by entity_id

homeassistant_list_scripts

List all scripts defined in Home Assistant

homeassistant_run_script

Execute a script by entity_id

homeassistant_list_input_booleans

List all input Boolean helpers in Home Assistant

homeassistant_toggle_input_boolean

Toggle the state of an input Boolean by entity_id and action

homeassistant_get_entity_history

Retrieve historical data for an entity over a specified time window

homeassistant_get_logbook

Fetch logbook entries for an entity or the system

homeassistant_get_events

List event types supported by Home Assistant

homeassistant_get_error_log

Retrieve the error log from Home Assistant

homeassistant_control_lights

Control lights including brightness, color, and state transitions

homeassistant_control_climate

Set temperature, HVAC modes, and presets on climate devices

homeassistant_control_media_player

Control media players with actions like play, pause, and volume changes

homeassistant_control_covers

Open/close covers and set positions for covers or blinds

homeassistant_get_devices_by_type

List devices filtered by domain/type

homeassistant_send_notification

Send a notification via a specified Home Assistant service

homeassistant_system_info

Retrieve system information for the Home Assistant instance

homeassistant_render_template

Render a Jinja2 template via Home Assistant

homeassistant_list_areas

List areas defined in Home Assistant

homeassistant_list_devices

List all devices managed by Home Assistant

homeassistant_list_integrations

List integrations available in Home Assistant

homeassistant_restart_service

Restart Home Assistant services with optional confirmation

homeassistant_supervisor_info

Get information about the Home Assistant Supervisor

homeassistant_list_addons

List add-ons installed in Home Assistant

homeassistant_search_entities

Search entities by text with optional domain filtering