# Home Assistant MCP > Home Assistant MCP Server gives your AI client direct control over your entire smart home. Use the Home Assistant REST API to manage lights, climate, media players, and read real-time sensor data. It exposes tools to list all devices, check current states, set temperatures, and trigger complex automations—all from a single API connection. ## Overview - **Category:** superpower - **Price:** Free - **Tags:** smart-home, home-automation, device-control, local-control, automation-triggers ## Description Your AI client gets direct control over your whole smart home. You're using the Home Assistant REST API through this server, which lets your agent manage lights, climate, media players, and read real-time sensor data. It exposes tools to list every device, check current states, set temperatures, and trigger complex automations—all from one API connection. **Reading Device Status** Use `list_entity_states` to get the current state, attributes, and IDs for every device connected to Home Assistant. You can then use `get_entity_state` to check the immediate, live status of a single device. For a full timeline, `get_entity_history` fetches a record of how a specific device's state changed over time, while `get_logbook_entries` lets you query system logs for a history of events across the entire system. **Executing Device Commands** Use `call_ha_service` to send specific commands to any Home Assistant domain, like turning on a light or adjusting a thermostat's temperature. You can also use this service call to trigger pre-written automations, forcing complex routines to run. **Discovering System Components** To see what your system can actually do, you can use `list_available_services` to list every action the system supports (like `light.turn_on` or `climate.set_temperature`). You can also check what integrations and software components are installed with `list_ha_components` and see all the calendar sources connected with `list_ha_calendars`. **System Checks and Configuration** `get_api_status` confirms if the Home Assistant API connection is active and running. You can also check the overall structural integrity of your setup using `check_ha_configuration`, or grab general system details with `get_ha_config`. Want to know what custom events the system tracks? `list_ha_events` shows all custom event types, and `list_ha_components` lists all installed hardware integrations and software components in HA. **Complex Calculations and Event Handling** `render_ha_template` processes a Jinja2 template and returns the result, which is useful for complex state calculations. You can also force custom routines to start by triggering a custom, user-defined event with `fire_ha_event`. To find upcoming appointments, you've got `get_calendar_events` which pulls events from any linked calendar. If you need to know what services are available for your system, `list_available_services` shows you everything. The system can also process a specific service call using `call_ha_service` to manage various HA domains, like lights, switches, climate, and media players. ## Tools ### call_ha_service Executes a specific action (service call) across any HA domain, like turning on a light or setting a thermostat temperature. ### check_ha_configuration Validates the overall structural integrity of your Home Assistant setup. ### fire_ha_event Triggers a custom, user-defined event in Home Assistant, which can start automations. ### get_api_status Checks if the Home Assistant API connection is active and running. ### get_calendar_events Retrieves upcoming events from any calendar linked to Home Assistant. ### get_entity_history Fetches a record of how a specific device's state has changed over a given time period. ### get_entity_state Gets the immediate, current status (state) of a single, specified smart device entity ID. ### get_ha_config Retrieves general configuration details about the Home Assistant system. ### get_logbook_entries Queries system logs to see a history of events and state changes across the entire system. ### list_available_services Lists all services and actions (like `light.turn_on` or `climate.set_temperature`) that the system can execute. ### list_entity_states Lists the current state, attributes, and IDs of every single device connected to Home Assistant. ### list_ha_calendars Shows all the calendar sources connected to Home Assistant. ### list_ha_components Lists all installed hardware integrations and software components in HA. ### list_ha_events Shows all custom event types currently tracked by Home Assistant. ### render_ha_template Processes and returns the result of a Jinja2 template, useful for complex state calculations. ## Prompt Examples **Prompt:** ``` List all my smart home entities and show me the lights. ``` **Response:** ``` I found 47 entities in your Home Assistant instance. Here are the lights: light.living_room (on, brightness: 128), light.kitchen (off), light.bedroom (on, brightness: 200, color_temp: 370), light.office (off). Would you like to control any of these? ``` **Prompt:** ``` Turn on the living room light and set it to 50% brightness. ``` **Response:** ``` Calling light.turn_on on light.living_room with brightness 128 (50%)... Done! The living room light is now on at 50% brightness. ``` **Prompt:** ``` What is the current temperature in the bedroom and what mode is the thermostat? ``` **Response:** ``` Checking climate.bedroom... Current temperature: 21.5°C. The thermostat is in 'heat' mode with a target temperature of 22°C. Humidity is 45%. ``` ## Capabilities ### Read Device Status Use `list_entity_states` and `get_entity_state` to retrieve the current state (on/off, temperature, etc.) of any known smart home device. ### Execute Device Commands Use `call_ha_service` to send specific commands, like setting a temperature (`climate.set_temperature`) or changing light brightness (`light.turn_on`). ### Monitor Event History Use `get_logbook_entries` and `get_entity_history` to query when and how a device's state changed over time. ### Trigger Routines Use `call_ha_service` with `automation.trigger` to force a complex, pre-written automation sequence to run. ### Discover System Components Use `list_available_services` and `list_ha_components` to see exactly what actions and integrations your smart home system supports. ## Use Cases ### The Morning Routine Check A property manager needs to know if the climate control is set correctly before showing a unit. They ask their agent: 'What's the status of the bedroom climate and the living room lights?' The agent uses `get_entity_state` for both, getting two specific status reports. The manager confirms the temp is 21°C and the lights are off, solving the issue without opening any dashboards. ### Debugging a Failed Automation The smart home enthusiast's morning routine failed. Instead of clicking through a confusing series of UI logs, they ask their agent to 'Check the logbook for the failure.' The agent uses `get_logbook_entries`, narrowing the time window and entity, and instantly identifies the failing service call, allowing for a quick fix. ### The Remote Guest Welcome A property manager needs to prepare a guest room for arrival. They tell their agent: 'Set the bedroom temperature to 22 and turn on the accent lights.' The agent uses `call_ha_service` twice—once for `climate.set_temperature` and once for `light.turn_on`—ensuring the room is ready before the guest arrives. ### System Audit and Discovery A developer setting up a new integration needs to know what actions are available. They ask their agent to 'List all possible services.' The agent uses `list_available_services`, giving the developer a complete manifest of every function they can call, saving hours of manual API documentation reading. ## Benefits - Control everything with `call_ha_service`. Instead of hitting the HA UI to adjust a dimmer or switch a fan, your agent sends a direct, targeted service call. This gives you immediate, programmatic control over any device domain (light, switch, climate, etc.). - See real-time status with `list_entity_states`. You don't have to open the dashboard to check if the bedroom light is on or what the current temperature is. The agent pulls the live state of all entities in one call. - Audit system changes with `get_logbook_entries`. When something goes wrong, you can't just guess. You query the logbook to see exactly when a device changed state and what triggered it. - Run complex routines with `call_ha_service`. Instead of manually setting the lights, lowering the blinds, and adjusting the heat, you call a single service to trigger a pre-written automation. - Understand dependencies with `list_available_services`. Before building a complex workflow, you check this tool to know exactly which actions (e.g., `cover.open_cover`) are possible for your devices. - Calculate derived values with `render_ha_template`. You can't just read a number; sometimes you need to run a template (like combining humidity and temperature) to get a useful metric. This tool handles that calculation. ## How It Works The bottom line is, your AI client talks to us, and we talk to your smart home system via the official Home Assistant API. 1. Subscribe to the server and provide your Home Assistant URL and a long-lived Access Token. 2. Your AI client uses the exposed tools (like `list_entity_states`) to read the current state of devices. 3. The server sends the action request to your Home Assistant instance, which executes the command and returns the resulting state. ## Frequently Asked Questions **How do I use the `get_entity_state` tool with Home Assistant MCP Server?** You provide the exact entity ID (e.g., `light.living_room`). This tool returns the current state, attributes, and last changed time for that single device, making it fast and targeted. **Can I use `call_ha_service` to run an automation?** Yes. You call the `automation.trigger` service, specifying the automation's entity ID. This forces the automation to run, regardless of its usual trigger conditions. **What is the difference between `get_entity_state` and `get_entity_history`?** `get_entity_state` gives the immediate, current state. `get_entity_history` gives a record of how the state changed over time, useful for identifying patterns or failures. **How do I find out what services I can call with `list_available_services`?** Simply run `list_available_services`. It returns a list of all domains and services (like `light: turn_on`) that are available to your agent, acting as a full API manifest. **Does Home Assistant MCP Server work with local or cloud instances?** It works with both local instances (via IP) and Nabu Casa cloud instances, giving you flexible control over your smart home setup. **How do I check the API connection status using `get_api_status`?** Use `get_api_status` to confirm the Home Assistant API is running. This is the first step before making any other calls, ensuring connectivity before you attempt device control. **What is the best way to list all available devices using `list_entity_states`?** Running `list_entity_states` provides a list of every entity ID and its current state. You can then filter this list to find specific types, like lights or sensors, to narrow down your targets. **How do I query past changes using `get_entity_history`?** You must specify the entity ID and a time range when calling `get_entity_history`. This returns a log of state changes, allowing you to analyze trends and past device behavior. **What Home Assistant URL should I use?** For local instances, use your Home Assistant's local network URL: `http://YOUR_IP:8123` (or `http://homeassistant.local:8123`). For cloud access via Nabu Casa, use your remote URL: `https://YOUR_INSTANCE.ui.nabu.casa`. The API is accessible at the same base URL as your Home Assistant frontend. **How do I get a Long-Lived Access Token?** Log in to your Home Assistant web interface, go to your user profile (click your name in the sidebar, then **Profile**), scroll down to **Long-Lived Access Tokens**, click **Create Token**, give it a name (e.g., 'MCP Server'), and copy the generated token. This token never expires unless manually revoked. **What devices and integrations are supported?** All Home Assistant integrations are supported since the API works at the service/state level. This includes lights (Philips Hue, LIFX, etc.), thermostats (Nest, Ecobee, etc.), covers/blinds, switches, media players (Sonos, Chromecast, etc.), sensors, cameras, locks, vacuums, and 1000+ other integrations. Use `list_entity_states` to discover all available entities. **Can I trigger Home Assistant automations from the API?** Yes! You can trigger automations in multiple ways: 1) Call the `automation.trigger` service directly, 2) Fire a custom event using `fire_ha_event` that matches an event trigger in your automation, 3) Call the `script.turn_on` service to run scripts. You can also control devices directly which will trigger related automations.