# Home Assistant MCP

> Home Assistant MCP connects your smart home ecosystem—lights, thermostats, media players, and sensors—to any AI agent. Use natural language prompts to monitor device status or run complex automations across local or cloud-based Home Assistant instances.

## Overview
- **Category:** superpower
- **Price:** Free
- **Tags:** smart-home, home-automation, device-control, local-control, automation-triggers

## Description

Connecting your entire smart house to an AI client is simple. This MCP lets you use conversation to manage everything from turning lights on and off to adjusting the climate temperature.

Your agent talks directly to your home's central hub via the REST API. You can ask it what the current humidity level is, check if a specific door sensor was tripped, or even tell it to run an entire automation sequence—all without opening a single app dashboard. It’s like having a dedicated smart home professional that lives inside your AI workflow.

If you're building complex systems and need reliable connections across multiple platforms, Vinkius provides the central point where your agent can talk to thousands of services, making this connection effortless. You get real-time data on every entity, history logs for troubleshooting, and control over specific devices—all from one prompt.

## Tools

### get_api_status
Run a quick test to confirm the Home Assistant API is online and ready for commands.

### get_calendar_events
Retrieves scheduled events from any calendar linked in your system.

### list_ha_calendars
Shows all the individual calendars configured within Home Assistant.

### check_ha_configuration
Validates the overall configuration of your Home Assistant system for errors.

### list_ha_components
Lists all major integrations and components that are currently running in Home Assistant.

### get_ha_config
Retrieves detailed information about the overall system configuration settings.

### list_ha_events
Shows every type of custom event that is actively tracked by your Home Assistant setup.

### get_entity_state
Checks the current status of one specific device or sensor using its unique ID.

### get_entity_history
Gathers historical data points for a single entity, helping you analyze usage patterns over time.

### get_logbook_entries
Retrieves a chronological list of significant activity entries and system logs.

### render_ha_template
Executes complex template code using Jinja2 to calculate or format advanced state data.

### list_available_services
Displays a comprehensive list of all actions (services) that can be performed across every device domain.

### list_entity_states
Lists the current state, last change time, and attributes for every connected entity.

### call_ha_service
The main function: it executes any specific service call, like turning on a light or setting a temperature.

### fire_ha_event
Sends a custom, triggered event to initiate automations elsewhere in the system.

## 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

### Check device status
The agent lists all connected smart home components and tells you their current operating state.

### Adjust physical devices
You can tell the system to change settings, like setting a thermostat temperature or dimming lights.

### Trigger complex actions
The agent runs predefined automations and sends custom events through your home network.

### Manage calendar data
You can list or query scheduled events stored in Home Assistant calendars.

## Use Cases

### Checking security status after a power outage
A property manager asks their agent, 'What is the current state of all door and window sensors?' The agent uses `list_entity_states` to report back whether every access point was properly secured or if any were left open.

### Setting up a movie night routine
A user prompts, 'Start Movie Night.' The agent executes multiple commands using `call_ha_service`: it dims the lights, lowers the motorized blinds (cover), and turns on the media player.

### Investigating a temperature fluctuation
An automation engineer asks the agent to check climate data. The agent uses `get_entity_history` on the thermostat entity to show a graph of how the temperature drifted over the last six hours, identifying when the HVAC system failed.

### Running complex scripts for testing
A developer wants to test a new automation sequence. Instead of triggering it manually, they use `fire_ha_event` with a custom event type, ensuring their workflow logic works correctly without physical intervention.

## Benefits

- Instant device status checks. Instead of navigating through multiple apps, you simply ask the agent to check a specific sensor's state using `get_entity_state`, and it tells you the number right away.
- Comprehensive control over all devices. You can adjust lights, set temperatures via `call_ha_service`, or even manage media playback—all through natural conversation without writing code.
- Deep operational visibility. Use `list_entity_states` to see every single device connected to your network at a glance, making it easy to find the exact ID you need for advanced scripting.
- Troubleshooting and auditing. When things go wrong, check historical data using `get_entity_history` or review system activity with `get_logbook_entries` to pinpoint exactly when an issue started.
- Advanced automation building. You can simulate triggers by running a custom event via `fire_ha_event`, allowing you to test your entire home's logic flow before deploying changes.

## How It Works

The bottom line is that it translates natural language commands into precise smart home actions.

1. Connect your Home Assistant instance URL and a long-lived access token to this MCP.
2. Tell your AI agent what you want done, for example: 'Set the living room lights to 50% brightness.'
3. Your agent sends the specific service command through the API, updating your physical devices in real time.

## Frequently Asked Questions

**How do I check if this Home Assistant MCP works with my local network?**
Yes, it supports both Nabu Casa cloud and local instances. You simply provide the correct URL format when configuring your agent's connection details.

**Can I use the get_entity_state tool to see all my devices?**
You can list everything using `list_entity_states`. This function returns a comprehensive list of every entity ID, its current status, and key attributes.

**What is the best way to control lights with Home Assistant MCP?**
Use the `call_ha_service` tool. You specify the domain (like 'light') and the service name (like 'turn_on'), along with any necessary parameters like brightness or color.

**Does this MCP help me troubleshoot my automations?**
Absolutely. By using `get_logbook_entries` and checking entity history via `get_entity_history`, you can trace back exactly when a state changed and why, solving tough automation puzzles.

**Do I need to know coding if I use the Home Assistant MCP?**
No. You don't write code; your agent does. You just talk naturally to it, letting it handle the API calls using tools like `call_ha_service` in the background.

**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.