Add a card to a dashboard view (live)

Args: url_path: Dashboard URL path, or None for the default dashboard. view: Target view — an integer index, or a string matching the view's path or title. card: The card config dict (must include a string type), e.g. {"type": "markdown", "content": "Hello"}. position: Insert index within the target card list (default: append). section: For a "sections"-type view, which section to add into — an index, section title, or heading text. REQUIRED for sections views (use list_view_sections to see them); omit for classic views. dry_run: Preview without saving.

Returns: Save result with a backup_id, or a dry-run preview.

Add a new view to a dashboard (live)

Args: url_path: Dashboard URL path, or None for the default dashboard. view_config: The view config dict, e.g. {"title": "Garage", "path": "garage"}. position: Insert index among views (default: append). dry_run: Preview without saving.

Returns: Save result with a backup_id, or a dry-run preview.

Call any Home Assistant service (low-level API access)

Args: domain: The domain of the service (e.g., 'light', 'switch', 'automation') service: The service to call (e.g., 'turn_on', 'turn_off', 'toggle') data: Optional data to pass to the service (e.g., {'entity_id': 'light.living_room'})

Returns: A dictionary with success status, the domain/service called, and the list of affected entity states returned by Home Assistant.

Examples: domain='light', service='turn_on', data={'entity_id': 'light.x', 'brightness': 255} domain='automation', service='reload' domain='fan', service='set_percentage', data={'entity_id': 'fan.x', 'percentage': 50}

Get a summary of entities in a specific domain

Args: domain: The domain to summarize (e.g., 'light', 'switch', 'sensor') example_limit: Maximum number of examples to include for each state

Returns: A dictionary containing: - total_count: Number of entities in the domain - state_distribution: Count of entities in each state - examples: Sample entities for each state - common_attributes: Most frequently occurring attributes

Examples: domain="light" - get light summary domain="climate", example_limit=5 - climate summary with more examples Best Practices: - Use this before retrieving all entities in a domain to understand what's available

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

Args: entity_id: The entity ID to control (e.g. 'light.living_room') action: The action to perform ('on', 'off', 'toggle') params: Optional dictionary of additional parameters for the service call

Returns: The response from Home Assistant

Examples: entity_id="light.living_room", action="on", params={"brightness": 255} entity_id="switch.garden_lights", action="off" entity_id="climate.living_room", action="on", params={"temperature": 22.5}

Domain-Specific Parameters: - 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)

Get a dashboard's full configuration

Args: url_path: The dashboard's URL path (e.g. "my-dash"). Omit or pass None for the default "Overview" dashboard.

Returns: The dashboard config dict (a top-level views list of cards). If the dashboard has no stored config yet, returns an empty {"views": []} scaffold with a note.

Get all entities assigned to a specific Home Assistant area (room).

Area lookup is case-insensitive and matches the area's name as configured in Home Assistant (e.g., "Kitchen", "Living Room"). Entities inherit their area from their parent device when no area is set directly, matching HA's own resolution behavior.

Args: area: Name of the area to filter by (case-insensitive) domain: Optional domain to further filter results (e.g., 'light') lean: If True (default), returns token-efficient entity records

Returns: A dictionary containing: - area: The matched area name (as canonicalized by HA) - count: Number of matching entities - entities: List of entity records with their state and area

Examples: get_entities_by_area(area="Kitchen") - everything in the kitchen get_entities_by_area(area="Living Room", domain="light") - lights only

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

Args: entity_id: The entity ID to get (e.g. 'light.living_room') fields: Optional list of fields to include (e.g. ['state', 'attr.brightness']) detailed: If True, returns all entity fields without filtering

Examples: entity_id="light.living_room" - basic state check entity_id="light.living_room", fields=["state", "attr.brightness"] - specific fields entity_id="light.living_room", detailed=True - all details

Get the Home Assistant error log for troubleshooting.

All filters are optional and combine (AND semantics). Stats (error_count, warning_count, integration_mentions, total_lines) are computed over the filtered output so they match what's returned.

Args: level: Filter to lines containing this log level — ERROR, WARNING, INFO, or DEBUG. Case-insensitive. integration: Filter to lines mentioning this integration. Matches [name] or [homeassistant.components.name]. Case-insensitive. search_term: Case-insensitive substring filter applied per line. Useful for entity IDs, exception names, etc. lines: Return only the most recent N lines (applied after other filters). Useful when you only care about the tail.

Returns: A dictionary containing: - log_text: The (possibly filtered) error log text - error_count: Number of ERROR entries in the filtered output - warning_count: Number of WARNING entries in the filtered output - integration_mentions: Map of integration names to mention counts - total_lines: Number of lines in the filtered output - filters_applied: Map of which filter args were supplied - error: Error message if retrieval failed

Examples: get_error_log() # full log get_error_log(level="ERROR") # errors only get_error_log(integration="zwave_js") # one integration get_error_log(search_term="light.kitchen") # specific entity get_error_log(level="ERROR", lines=50) # last 50 errors

Best Practices: - Filter on the server side (here) rather than pulling the full log into Claude's context — saves tokens on noisy logs. - Combine integration + level="ERROR" to triage a single integration that's misbehaving. - Use lines to bound output when scanning a long-running HA.

Get the history of an entity's state changes

Args: entity_id: The entity ID to get history for hours: Number of hours of history to retrieve (default: 24)

Returns: A dictionary containing: - entity_id: The entity ID requested - states: List of state objects with timestamps - count: Number of state changes found - first_changed: Timestamp of earliest state change - last_changed: Timestamp of most recent state change

Examples: entity_id="light.living_room" - get 24h history entity_id="sensor.temperature", hours=168 - get 7 day history Best Practices: - Keep hours reasonable (24-72) for token efficiency - Use for entities with discrete state changes rather than continuously changing sensors - Consider the state distribution rather than every individual state

Get raw state-change history for an entity over a date/time range.

Like get_history, but takes an explicit window instead of "N hours from now". Useful for inspecting what happened on a specific day or correlating with an external event.

Args: entity_id: The entity to fetch history for. start_time: ISO-8601 start (e.g. 2026-05-15 or 2026-05-15T08:00:00Z). Treated as UTC if no offset. end_time: ISO-8601 end. Defaults to now (UTC).

Returns: Same shape as get_history: entity_id, states, count, first_changed, last_changed.

Examples: get_history_range("light.kitchen", "2026-05-15") get_history_range("sensor.power", "2026-05-15T00:00:00Z", "2026-05-16T00:00:00Z")

Best Practices: - Bound the window — wider ranges return more data and more tokens. - For aggregated long-term data, prefer get_statistics_range.

Get long-term aggregated statistics for an entity over the last N hours.

Uses HA's recorder statistics (over WebSocket) — aggregated buckets (mean / min / max per period) that survive the short-term retention window. Use this instead of get_history when: - You want data older than the recorder's default 10-day window. - You want aggregated values rather than every individual change. - The entity is a high-frequency sensor (temperature, power) and raw history would be too many tokens.

Args: entity_id: The entity (must have a state_class HA records as statistics — measurement, total, total_increasing). hours: How far back from now. Defaults to 24. period: Bucket size — 5minute, hour, day, week, month. Defaults to hour.

Returns: entity_id, period, start_time, end_time, statistics (list of {start, end, mean, min, max, ...} points).

Examples: get_statistics("sensor.power_usage", hours=168, period="day") get_statistics("sensor.temperature", hours=24)

Get long-term aggregated statistics for an entity over a date/time range.

Same data source as get_statistics, but with an explicit window — useful for "what was my power usage from Jan 1 to Jan 31?" type questions. Aggregated bucket data survives the short-term retention window, so this works for data months/years old.

Args: entity_id: The entity (must be statistics-tracked). start_time: ISO-8601 start (2026-01-01 or 2026-01-01T00:00:00Z). UTC if no offset. end_time: ISO-8601 end. Defaults to now. period: 5minute, hour, day, week, or month.

Returns: entity_id, period, start_time, end_time, statistics.

Examples: get_statistics_range("sensor.energy", "2026-01-01", "2026-02-01", period="day") get_statistics_range("sensor.temperature", "2026-05-01", period="hour")

Get the Home Assistant version

Returns: A string with the Home Assistant version (e.g., "2025.3.0")

Get a list of all automations from Home Assistant

This function retrieves all automations configured in Home Assistant, including their IDs, entity IDs, state, and display names.

Returns: A list of automation dictionaries, each containing id, entity_id, state, and alias (friendly name) fields.

Examples: Returns all automation objects with state and friendly names

List on-disk backups of a dashboard's config

Backups are written automatically before every dashboard write. NOTE: in Docker, backups persist only if HASS_MCP_BACKUP_DIR is volume-mounted.

Args: url_path: Dashboard URL path, or None for the default dashboard.

Returns: A list of {backup_id, path}, oldest first.

List Home Assistant dashboards (Lovelace)

Returns: A list of dashboards. Each entry has url_path (None for the default "Overview" dashboard), title, and mode ("storage" or "yaml"). Only "storage"-mode dashboards can be edited via these tools.

Get a list of Home Assistant entities with optional filtering

Args: domain: Optional domain to filter by (e.g., 'light', 'switch', 'sensor') search_query: Optional search term to filter entities by name, id, or attributes (Note: Does not support wildcards. To get all entities, leave this empty) limit: Maximum number of entities to return (default: 100) fields: Optional list of specific fields to include in each entity detailed: If True, returns all entity fields without filtering

Returns: A list of entity dictionaries with lean formatting by default

Examples: domain="light" - get all lights search_query="kitchen", limit=20 - search entities domain="sensor", detailed=True - full sensor details

Best Practices: - Use lean format (default) for most operations - Prefer domain filtering over no filtering - For domain overviews, use domain_summary_tool instead of list_entities - Only request detailed=True when necessary for full attribute inspection - To get all entity types/domains, use list_entities without a domain filter, then extract domains from entity_ids

List the sections of a "sections"-type dashboard view

Modern Home Assistant views of type: sections hold their cards inside sections (not a top-level card list). Use this to discover which section to target with the card tools' section argument.

Args: url_path: Dashboard URL path, or None for the default dashboard. view: Target view (index, or matching path/title).

Returns: A list of {index, title, heading, card_count}, one per section. Errors if the view is not a sections view.

Reorder a card within a dashboard view (live)

Args: url_path: Dashboard URL path, or None for the default dashboard. view: Target view (index, or matching path/title). card_index: Current index of the card. new_index: Destination index within the same card list. section: For a "sections"-type view, which section the card is in (index/title/heading). Required for sections views. dry_run: Preview without saving.

Returns: Save result with a backup_id, or a dry-run preview.

Remove a card from a dashboard view (live)

Args: url_path: Dashboard URL path, or None for the default dashboard. view: Target view (index, or matching path/title). card_index: Index of the card to remove within the target card list. section: For a "sections"-type view, which section the card is in (index/title/heading). Required for sections views. dry_run: Preview without saving.

Returns: Save result with a backup_id, or a dry-run preview.

Remove a view from a dashboard (live)

⚠️ Removes the view and all its cards.

Args: url_path: Dashboard URL path, or None for the default dashboard. view: Target view (index, or matching path/title). dry_run: Preview without saving.

Returns: Save result with a backup_id, or a dry-run preview.

Restart Home Assistant

⚠️ WARNING: Temporarily disrupts all Home Assistant operations

Returns: Result of restart operation

Restore a dashboard from a backup (live)

Restores the most recent backup unless backup_id is given. The current config is itself backed up first, so a restore can be undone.

Args: url_path: Dashboard URL path, or None for the default dashboard. backup_id: A specific backup id from list_dashboard_backups (default: newest). dry_run: Preview without saving.

Returns: Save result plus restored_from, or a dry-run preview.

Search for entities matching a query string

Args: query: The search query to match against entity IDs, names, and attributes. (Note: Does not support wildcards. To get all entities, leave this blank or use list_entities tool) limit: Maximum number of results to return (default: 20)

Returns: A dictionary containing search results and metadata: - count: Total number of matching entities found - results: List of matching entities with essential information - domains: Map of domains with counts (e.g. {"light": 3, "sensor": 2})

Examples: query="temperature" - find temperature entities query="living room", limit=10 - find living room entities query="", limit=500 - list all entity types

Replace a dashboard's full configuration (low-level write)

⚠️ WARNING: Overwrites the ENTIRE dashboard and updates every open browser live. The prior config is backed up first (use restore_dashboard to undo). Requires an admin token; only storage-mode dashboards can be saved.

Args: url_path: Dashboard URL path, or None for the default dashboard. config: The complete new config dict (must contain a views list). dry_run: If True, validate and return the resulting config + a change summary WITHOUT saving.

Returns: On save: {success, url_path, backup_id, summary}. On dry_run: {dry_run: True, url_path, summary, config}.

Get a comprehensive overview of the entire Home Assistant system

Returns: A dictionary containing: - total_entities: Total count of all entities - domains: Dictionary of domains with their entity counts and state distributions - domain_samples: Representative sample entities for each domain (2-3 per domain) - domain_attributes: Common attributes for each domain - area_distribution: Entities grouped by area (if available)

Examples: Returns domain counts, sample entities, and common attributes Best Practices: - Use this as the first call when exploring an unfamiliar Home Assistant instance - Perfect for building context about the structure of the smart home - After getting an overview, use domain_summary_tool to dig deeper into specific domains

Replace a card in a dashboard view (live)

Args: url_path: Dashboard URL path, or None for the default dashboard. view: Target view (index, or matching path/title). card_index: Index of the card to replace within the target card list. card: The new card config dict (must include a string type). section: For a "sections"-type view, which section the card is in (index/title/heading). Required for sections views. dry_run: Preview without saving.

Returns: Save result with a backup_id, or a dry-run preview.

Update a view's properties — title, path, icon, etc. (live)

Cards in the view are preserved unless changes includes a cards key.

Args: url_path: Dashboard URL path, or None for the default dashboard. view: Target view (index, or matching path/title). changes: Dict of view properties to merge in, e.g. {"title": "New Title"}. dry_run: Preview without saving.

Returns: Save result with a backup_id, or a dry-run preview.