hass-mcp-plus

Get the Home Assistant version.

Get the state of a Home Assistant entity with optional field filtering.

Args: entity_id: Entity ID (e.g. 'light.living_room') fields: Fields to include (e.g. ['state', 'attr.brightness']) detailed: If True, returns all fields unfiltered

Examples: get_entity("light.living_room", fields=["state", "attr.brightness"])

Perform an action on a Home Assistant entity (on, off, toggle).

Args: entity_id: Entity ID to control (e.g. 'light.living_room') action: 'on', 'off', or 'toggle' params: Additional service parameters (e.g. {"brightness": 255, "temperature": 22.5})

Domain-specific params: Lights: brightness (0-255), color_temp, rgb_color, transition, effect Covers: position (0-100), tilt_position Climate: temperature, target_temp_high, target_temp_low, hvac_mode Media players: source, volume_level (0-1)

Examples: entity_action("light.living_room", "on", {"brightness": 255}) entity_action("switch.garden_lights", "off")

List Home Assistant entities with optional filtering.

Args: domain: Domain filter (e.g. 'light', 'switch', 'sensor') search_query: Search by name, id, or attributes (no wildcards) limit: Max entities to return (default: 100) fields: Specific fields to include per entity detailed: If True, returns all fields unfiltered compact: If True, returns only entity_id/state/friendly_name (overrides detailed/fields)

Examples: list_entities(domain="light") list_entities(search_query="kitchen", limit=20) list_entities(compact=True)

Search for entities matching a query string across IDs, names, and attributes.

Args: query: Search term (no wildcards; empty string returns all entities) limit: Max results (default: 20)

Examples: search_entities("temperature") search_entities("living room", limit=10)

Get a summary of entities in a domain (counts, state distribution, examples).

Args: domain: Domain to summarize (e.g. 'light', 'switch', 'sensor') example_limit: Max examples per state (default: 3)

Examples: domain_summary("light") domain_summary("climate", example_limit=5)

Get a comprehensive overview of the Home Assistant system (domain counts, samples, areas).

Good first call when exploring an unfamiliar instance. Use domain_summary to drill deeper.

List automations with their IDs, entity IDs, state, and aliases.

Args: limit: Max automations to return (1-200, default: 50)

Examples: list_automations() list_automations(limit=200)

List recent execution traces for a specific automation.

Args: automation_id: Automation ID (e.g. 'motion_light' or 'automation.motion_light') domain: 'automation' or 'script' (default: 'automation') limit: Max traces to return (default: 10, max: 50)

Use run_id from results with get_automation_trace for full details.

Examples: list_automation_traces("motion_light") list_automation_traces("kitchen_lights", limit=5)

Get detailed trace for a specific automation run (trigger, conditions, actions, errors).

Args: automation_id: Automation ID (e.g. 'motion_light') run_id: Run/trace ID from list_automation_traces domain: 'automation' or 'script' (default: 'automation')

Examples: get_automation_trace("motion_light", "1700000000.123456")

Restart Home Assistant. WARNING: Temporarily disrupts all operations.

Call any Home Assistant service directly (low-level API).

Args: domain: Service domain (e.g. 'light', 'automation') service: Service name (e.g. 'turn_on', 'reload') data: Service data (e.g. {'entity_id': 'light.x', 'brightness': 255})

Examples: call_service("light", "turn_on", {"entity_id": "light.x", "brightness": 255}) call_service("automation", "reload")

Get raw state changes for an entity. For aggregated trends, use get_statistics instead.

By default returns last N hours. Provide start_time to query a specific date range instead. Best for: exact state change timestamps, infrequently-changing entities (doors, switches), short time periods. NOT for: long ranges on frequently-updating sensors — use get_statistics.

Args: entity_id: Entity ID to get history for hours: Hours of history (default: 24). Ignored if start_time is provided. start_time: ISO 8601, date only, or 'yesterday'/'today'. If set, uses range mode instead of hours. end_time: End of range (default: 'now'). Only used with start_time. limit: Max records (1-500, default: 100) sample_strategy: 'recent' (default), 'first', or 'even' — how to sample if over limit minimal_response: Reduce response size in range mode (default: true)

Examples: get_history("binary_sensor.front_door") get_history("sensor.temperature", hours=1, limit=50) get_history("sensor.temp", start_time="2025-10-28T10:00:00Z", end_time="2025-10-28T11:00:00Z") get_history("light.living_room", start_time="yesterday", end_time="today")

Get aggregated statistics (mean/min/max) for an entity. Best tool for historical data — no token limits.

By default returns last N hours. Provide start_time to query a specific date range instead. Handles any range efficiently (days, months, years). If get_history hits token limits, use this tool with the same time range instead.

Args: entity_id: Entity ID to get statistics for hours: Hours of data (default: 24). Ignored if start_time is provided. start_time: ISO 8601, date only, or 'yesterday'/'today'. If set, uses range mode instead of hours. end_time: End of range (default: 'now'). Only used with start_time. period: Aggregation period (default: 'hour'): '5minute' (~12 points/hr), 'hour' (24/day), 'day' (monthly views), 'week' (quarterly), 'month' (yearly). Match period to time range.

Examples: get_statistics("sensor.temperature", hours=24, period="hour") get_statistics("sensor.power_usage", hours=168, period="day") get_statistics("sensor.temperature", start_time="2024-10-01", end_time="2024-10-31", period="day") get_statistics("sensor.humidity", start_time="yesterday", period="5minute")

Get the Home Assistant error log (WebSocket API). Stacktraces truncated by default.

Args: limit: Max records (1-100, default: 50) integration: Filter by integration (e.g. "mqtt", "zwave") level: Filter by level: "ERROR" or "WARNING" since_minutes: Only errors from last N minutes truncate_traces: Truncate stacktraces to 3 lines (default: True)

Examples: get_error_log(integration="mqtt") get_error_log(level="ERROR", since_minutes=60)

Get Home Assistant core logs (all levels) from the Supervisor journal, with fallback to error log.

Args: limit: Max records (1-200, default: 50) level: Filter: "DEBUG", "INFO", "WARNING", or "ERROR" integration: Filter by integration (e.g. "mqtt", "llmvision") pattern: Case-insensitive substring match on message since_minutes: Only logs from last N minutes lines: Journal lines to request (default: 500) truncate_traces: Truncate stacktraces to 3 lines (default: True)

Use set_log_level to enable DEBUG before reading debug logs; reset to WARNING after.

Examples: get_core_logs(level="DEBUG", integration="llmvision") get_core_logs(pattern="timeout", since_minutes=60)

Set the log level for a Home Assistant integration.

Args: integration: Integration name (e.g. "mqtt", "llmvision") level: "debug", "info", "warning", or "error" custom_component: If True, targets custom_components.X (for HACS integrations)

Examples: set_log_level("mqtt", "debug") set_log_level("llmvision", "debug", custom_component=True) set_log_level("mqtt", "warning") # reset to normal

Remove an entity from the entity registry. Two-phase safety: preview first, then confirm.

By default returns a preview. Set confirm=True to actually delete. Entity may reappear if integration recreates it; consider disable instead.

Args: entity_id: Entity ID to remove (e.g. 'light.old_device') confirm: False=preview (default), True=permanently remove

Examples: remove_entity("light.orphaned_device") # preview remove_entity("light.orphaned_device", confirm=True) # delete

Update entity registry properties (name, icon, area, disable/enable, hide/unhide, rename).

For fields that can be cleared, pass "none" as the string value to set to null.

Args: entity_id: Entity ID to update name: Friendly name (or "none" to clear) icon: Icon (e.g. 'mdi:lamp', or "none" to clear) disabled_by: "user" to disable, "none" to re-enable hidden_by: "user" to hide, "none" to unhide area_id: Area ID (or "none" to remove) new_entity_id: Rename entity ID (e.g. 'light.new_name') options: Platform options dict

Examples: update_entity("sensor.old", disabled_by="user") update_entity("sensor.old", disabled_by="none") # re-enable update_entity("light.x", name="Living Room Lamp", area_id="kitchen")

Get the full entity registry entry (platform, config, device, disabled/hidden, area).

Args: entity_id: Entity ID to look up (e.g. 'light.living_room')

Examples: get_entity_registry("light.living_room")

List entity registry entries (platform, config, disabled/hidden, area). Not states — use list_entities for states.

Args: domain: Domain filter (e.g. 'light', 'sensor') limit: Max entries (default: 100, max: 5000)

Examples: list_entity_registry(domain="light") list_entity_registry(domain="sensor", limit=50)

Query entities using CEL (Common Expression Language) expressions.

CEL context: entity_id (string), state (numeric if possible, else string), domain (string), attributes (dict).

Args: domain: Domain pre-filter (e.g. "sensor", "light") expression: CEL filter expression limit: Max entities (default: 50) lean: Minimal fields with domain-specific attrs (default: True) compact: Only entity_id/state/friendly_name (default: False)

CEL examples: domain="sensor", expression='state < 30 && attributes.device_class == "battery"' domain="light", expression='state == "on" && attributes.brightness < 50' expression='state == "unavailable" || state == "unknown"'