Ha MCP Readonly

[READ] Analyzes logs and returns intelligent summary of errors and warnings.

[READ] Find orphan entities, never-triggered automations, broken entity references, and unused blueprints.

Scans entity registry, automations, scripts, scenes, dashboards, and blueprints to identify configuration drift and unused resources.

Args: None

Returns: JSON with:

• orphan_entities: entities never used in automations/scripts/scenes/dashboards
• never_triggered_automations: automations with no last_triggered
• broken_references: entity references in configs but missing from registry
• unused_blueprints: blueprint files not used by any automation or script
• summary: plain-text summary string

[READ] Validate that all trigger ids in an automation have corresponding handlers.

Checks automation configuration for:

• Triggers with ids that have no corresponding choose/parallel/if blocks
• Orphaned trigger ids
• Duplicate trigger ids
• Missing trigger ids in conditions/actions

[READ] Search multiple terms at once. Saves ~85% tokens vs individual searches.

[READ] Compare entity states before/after changes. Saves ~70% tokens vs manual checking.

[READ] Compare a previously taken health snapshot with the current state. Shows new and resolved unavailable entities.

[READ] Return the supported catalog and active deployment profile.

This is a zero-I/O introspection tool. It lets an AI agent inspect every governed capability's risk, side effects, activation state and inactive reason without invoking the operation itself.

Args: None.

Returns: JSON string with a `success` flag and a payload containing the supported and active catalog counts plus per-tool manifests.

[READ] Get WiFi status for Tasmota/OpenBK devices.

Queries the device directly via HTTP if available, or returns cached status from Home Assistant sensors.

[READ] Comprehensive automation diagnostics with entity resolution, template validation, and usage analysis. ~75% token savings.

~75% token savings when analyzing automations. Instead of: get_automation_code() + check_entity_exists() × N + test_template() × M

[READ] Detect duplicate automation aliases from YAML and UI sources.

Groups all automations by alias and flags groups of 2+ entries with the same display name, categorizing the impact as all_disabled, all_enabled, or mixed.

Returns: JSON with:

• duplicates: list of groups with alias, entities, and impact
• total_duplicates: number of duplicate groups

[READ] Detect mismatches between automation alias prefixes and assigned categories.

For each automation, extracts the prefix from the alias and verifies that the assigned category matches the canonical prefix-to-category mapping.

Returns: JSON with mismatches list containing entity_id, alias, alias_prefix, assigned_category_name, expected_category_name, and severity.

[READ] Provide diagnostics for a config entry using registry, API, and logs.

[READ] Diagnose network and API connectivity issues across integrations. Checks system health and log retry patterns.

Args: (none)

Returns: JSON with overall_status, connectivity_issues list, retry_patterns, and recommendations.

[READ] Detect sensors approaching their input_number threshold limits.

Matches sensor.* entities to input_number.* threshold helpers by naming convention and flags pairs where the sensor value is within proximity_percent of the threshold.

[READ] Detect Home Assistant installation type (OS, Supervised, Container, or Core) and list feature constraints.

Args: (none)

Returns: JSON with type, version, constraints list, and available_features list.

[READ] Full Lovelace diagnostics: missing entity references, strategy/YAML mode, resource analysis, recommendations. ~85% token savings.

Checks: missing entity references, strategy/YAML mode dashboards, resource analysis, and generates recommendations. ~85% token savings vs manual multi-call workflow.

Returns: JSON with dashboard stats, resource analysis, health_checks (missing entity references, strategy/YAML mode), issues, and recommendations.

[READ] Finds entity_id references in automations/scripts that do not exist in Home Assistant.

Extracts every entity_id referenced in automations.yaml (and optionally scripts.yaml), then cross-references with the live entity list from /api/states to identify orphaned references.

[READ] Analyze system performance: slow automations, entities with large attribute payloads, and trigger frequency.

Args: (none)

Returns: JSON with slowest_automations, largest_entities, and summary.

[READ] Full person tracking diagnostics: entity state, tracker freshness, zone proximity, and related automations. ~85% token savings.

Aggregates ~6 individual calls into one:

• Person entity state + device trackers
• Each tracker: state, freshness, accuracy, integration type
• Zones near the person (entered/at boundary)
• Automations using this person entity
• Recommendations for tracking reliability

[READ] Check custom integrations after a Home Assistant update. Highlights known-fragile integrations and load failures.

Args: (none)

Returns: JSON with custom_components_total, loaded/failed counts, fragile_highlighted, per_integration details, and recommendations.

[READ] Detects entities whose last_updated timestamp exceeds the threshold.

Scans camera, sensor, and binary_sensor entities for stale data. Flags entities with severity based on age: critical (>60min), warning (>15min), info (>5min). Groups results by integration domain.

[READ] Estimate Home Assistant startup progress by counting entities, loaded integrations, and active automations.

Args: (none)

Returns: JSON with entity_count, integrations_loaded/total, automations_on/total, progress_pct, and status.

[READ] Detects input_boolean, timer, and counter entities stuck in one state.

Scans helper entities and flags those whose `last_changed timestamp is older than stale_hours`. Useful for catching restart-interrupted delay patterns and broken automations.

[READ] Complete system diagnostics: health score, error patterns, unavailable entities, performance issues, and recommendations in a single call.

Provides everything needed for AI-driven diagnosis:

• Health Score and summary
• Top error patterns with affected entities
• Unavailable entities grouped by integration
• Slow entities (performance issues)
• API errors
• Recommendations

[READ] Scans entity registry for automations without a category assigned.

Filters entities with empty categories dict and optionally suggests a category based on the alias prefix.

[READ] Diagnose voice assistant configuration: exposed entities, available STT/TTS/conversation agents, and pipelines.

Args: (none)

Returns: JSON with exposed_entities_count, assistants_available, pipelines, issues, and recommendations.

[READ] Trace the sources of changes for an entity.

Analyzes automation traces, logbook entries, and history to determine what triggered recent state changes.

[READ] Get all entities and their states.

Warning: may return 1000+ entities. Use get_states_filtered for filtering.

[READ] Analyze what is happening in a room: devices, automations related to those devices, and recent activity.

[READ] Summary of devices in an area.

~80% token savings vs get_area_overview() + get_device_registry().

[READ] Full area/room diagnostics in a single query: devices, entities, automations, and sensor readings.

[READ] BATCH ENDPOINT - Comprehensive area overview.

~70% token savings when analyzing an area. Instead of: get_area_registry() + filter entities + get states × N

[READ] Fetches registry of all areas/rooms from .storage. Contains: name, aliases, picture, icon.

[READ] Fetches full automation code (without 'id' - ready to paste in UI).

[READ] Get YAML code for multiple automations at once. Saves ~70% tokens vs N individual calls.

[READ] Detect potential conflicts where multiple automations modify the same entity, which may cause flickering or unexpected states. Detects if a given entity is modified by multiple automations at once (which may cause light flickering or unexpected states).

[READ] Analyze automation dependencies: lists used entities, scripts, scenes, and blueprints.

[READ] Resolve automation alias to entity_id. Searches HA entity registry for automation.* entities matching by friendly_name (alias).

[READ] Returns the file path and line numbers (line_start, line_end) of an automation in automations.yaml.

Use this to locate an automation's exact position before reading surrounding context with read_config_file(offset=line_start, limit=...). Eliminates manual grep + read steps.

[READ] Get automation usage statistics: run count, last triggered time, recent activity from history.

Target: Automation usage statistics.

[READ] Fetches full source YAML code of a blueprint.

[READ] Find all automations and scripts that use a specific blueprint.

[READ] Summary of blueprint usage.

Returns: JSON with summary (most used blueprints, unused, etc.)

[READ] Return registry cache hit/miss/blocked statistics.

Returns cache performance data including hit rate percentage, total hits, misses, blocked requests, and number of cached keys.

Returns: JSON with hits, misses, blocked, total, hit_rate_percent, and cached_keys fields.

[READ] Fetches all logs related to a specific component/integration.

[READ] Fetches all configuration entries of integrations. Shows installed integrations, their domains, titles, versions, options.

[READ] Get details for a single config entry with full context.

[READ] Returns structure of directories and files in the Home Assistant configuration directory.

Returns: JSON with directory tree structure of the HA config directory.

[READ] Trace the context parent_id chain for entity state changes.

Follows context.parent_id links from logbook entries to reconstruct the chain of events that led to a state change (e.g. automation → script → light).

[READ] Fetches list of counters with their configuration.

Returns: JSON with total_counters count and counters list.

[READ] Fetches device details with full context.

~90% token savings vs get_device_registry() + filtering.

[READ] Fetches list of entities belonging to a device.

[READ] Fetches registry of all devices from .storage. Contains: name, manufacturer, model, sw_version, connections, identifiers.

[READ] Retrieve available device triggers for a device.

[READ] Fetches all devices in a given area.

[READ] Return summary of how many entities are in each domain. Useful for quick system overview without fetching all states.

Returns: JSON with total entity and domain counts, and per-domain totals broken down by unavailable and unknown states.

[READ] Get energy dashboard summary: current power, tariff info, daily consumption, and cost analysis.

Returns: JSON with tariff status, consumption figures, detected sensor counts, and recommendations.

[READ] Detect entities that changed state recently. Useful for "what changed in the last hour?" queries.

Useful for:

• "What changed in the last hour?"
• "Which lights were turned on/off?"
• "Which sensors activated?"

[READ] List of automations and scripts using a given entity (simplified version).

[READ] Get comprehensive entity context: state, registry info, related entities, automations, and device details. ~75% token savings.

~75% token savings when analyzing an entity. Instead of: get_entity_details() + get_entity_state() + search related entities

[READ] Finds all places where entity is used (reverse lookup).

~85% token savings vs manually searching files.

[READ] Fetches detailed information about a specific entity from the registry. Contains related device and area.

Warning: Use get_entity_context() for full context with live state.

[READ] Fetches registry of all entities from .storage. Contains: entity_id, platform, device_id, aliases, disabled_by, hidden_by.

Warning: returns all entities - use search_registries_batch() for filtering.

[READ] Fetch entity registry entries with optional filtering by entity IDs and fields.

[READ] Get detailed state of a single entity.

[READ] Batch: get states for a list of entities in one request.

[READ] Summarize entity state history instead of returning raw rows.

[READ] Composite: full entity context + automations + conflicts in one call.

Replaces multiple calls: get_entity_context + search_automations_by_entity + get_automation_conflicts.

[READ] Fetches list of entities exposed to voice assistants (Google Assistant, Alexa).

Returns: JSON with total_exposed count and entities exposed to voice assistants.

[READ] Fetches HACS data (Home Assistant Community Store). Shows installed custom integrations and themes.

Returns: JSON with the full HACS storage data (repositories, categories), or an info message when HACS is not installed.

[READ] Fetch history of state changes for a list of entities. ~85% token savings when analyzing history.

~85% token savings when analyzing history.

[READ] Get entity history statistics: min, max, average values from the recorder. ~90% token savings vs raw history.

Returns processed data (Min, Max, Average) instead of raw list. ~90% token savings when analyzing history.

[READ] Fetches all input helpers (input_boolean, input_number, input_select, input_text, input_datetime, input_button).

Returns: JSON with helper type keys (input_boolean, input_number, input_select, input_text, input_datetime, input_button), each with count and items.

[READ] Get all entities for a given integration domain.

[READ] Get detailed health status of a specific integration domain (e.g. "mqtt", "tuya", "zha").

[READ] Summarize an integration (devices, entities, health).

[READ] Intelligent log analysis: grouped error patterns, affected entities, problem categories, timeline, and fix recommendations. ~85% token savings.

Returns:

• Grouped errors with affected entities and affected automations
• Problem categorization
• Timeline summary
• Fix recommendations

[READ] Creates timeline of errors and warnings from last N hours.

[READ] Fetches configuration of a specific Lovelace dashboard.

[READ] Token-efficient Lovelace dashboard structure overview: card type breakdown, view counts, strategy detection. ~95% token savings.

Returns card counts, type breakdown, view info. ~95% token savings vs returning full dashboard JSON.

[READ] Fetches list of all Lovelace dashboards.

Returns: JSON with total_dashboards count and dashboards list.

[READ] Locate an entity across all Lovelace dashboards.

[READ] Fetches list of registered Lovelace resources (custom cards, JS modules, CSS).

Returns: JSON with resource list, type breakdown, and source classification.

[READ] Fetches main configuration from file configuration.yaml. Returns structured YAML, with sensitive data (passwords, tokens) redacted.

Returns: JSON with sanitized configuration data as a YAML string.

[READ] List NFC tags with automation usage info.

Reads from .storage/core.tag registry, falls back to /api/states for tag.* entities. Cross-references each tag against automations.yaml to determine usage.

Args: None

Returns: JSON with tags list (tag_id, name, last_scanned, used_in_automations), total count, and unused_count.

[READ] Check active persistent notifications in Home Assistant.

Returns: JSON with active persistent notifications, recent notifications from the last 24 hours, and counts for both.

[READ] Fetches list of people (person entities) with their configuration.

Returns: JSON with total_persons count and persons list.

[READ] Fetches last N lines from previous log.

[READ] Fetches last N lines from current log.

[READ] Retrieve all state changes from the last `minutes` minutes.

[READ] Fetches full code of a specific scene.

[READ] Fetches full code of a specific script.

[READ] Get list of available services and domains.

[READ] Analyzes startup logs and returns errors/warnings from last startup.

Returns: JSON with startup errors and warnings, and total counts for each.

[READ] Server-side filtering of entities.

[READ] Group entity states instead of listing all.

[READ] Batch endpoint: complete system overview in one call.

[READ] Get all entities referenced in a template. Saves ~90% tokens vs manual analysis.

[READ] Fetches template sensors and binary_sensors created via UI. Template helpers are stored in .storage/core.config_entries.

[READ] Batch fetch template entity code for multiple entities.

[READ] Returns full Jinja2 template code for a single template helper entity. ~95% token savings vs get_template_entities().

[READ] Fetches list of timers with their configuration.

Returns: JSON with total_timers count and timers list.

[READ] Group unavailable entities by integration or domain for efficient health analysis. ~95% token savings vs listing all.

Instead of returning 200+ entities (48k tokens), groups them by integration (~2k tokens).

[READ] Fetches list of zones with their configuration.

Returns: JSON with total_zones count and zones list.

[READ] Build or refresh the HA Semantic Graph from configuration files and registries.

[READ] Detect entity references that no longer exist in the entity registry.

Returns: JSON with list of ghost entity IDs (referenced in config but not in registry).

[READ] Detect entities in the registry with no incoming edges.

[READ] Analyze the potential impact of modifying or removing an entity.

[READ] Export a subgraph as Mermaid flowchart syntax for visualization.

[READ] Find all semantic references to an entity in the HA graph.

[READ] Get the subgraph around a specific node in the HA semantic graph.

[READ] Get HACS repository update counts, critical updates, and major version bumps.

Lightweight statistics from hacs.data — total installed, updates available, critical updates, and major version bumps (e.g. v1.x -> v2.x).

Args: None

Returns: JSON with total_installed, updates_available, critical_updates list, major_version_bumps list.

[READ] Super function: comprehensive diagnostics for entity/area in one call.

Replaces multiple queries (search_entities, get_entity_context, get_entity_state, automation searches, area overview, conflict analysis, entity state batch). Token-optimized response.

[READ] Lists all Home Assistant categories with their IDs, names, and icons.

Reads the category registry to discover organisational categories for automations, scripts, scenes, and helpers. Optionally counts how many entities are assigned to each category.

[READ] Fetches list of names and ids of all automations.

Warning: returns all 111 automations - use search_automations() if looking for a specific one.

[READ] Fetches list of all available blueprints. Scans 'automation' and 'script' directories in the blueprints folder.

Returns: JSON with list of blueprints (name, path, description, author, input count).

Example: list_blueprints()

[READ] List all domains (integrations) with counts of config entries.

Returns: JSON with total entry count, total domain count, and per-domain entry and disabled counts.

[READ] Fetches list of installed custom components (custom_components/).

Returns: JSON with total component count and per-component name, path, version, and domain metadata.

[READ] List directory contents with allowlist validation.

[READ] Fetches list of all scenes from scenes.yaml.

Returns scene names and their basic information.

Args: None

Returns: JSON with list of scenes.

[READ] Fetches list of all scripts from scripts.yaml.

Returns script names and their descriptions.

Args: None

Returns: JSON with list of scripts.

[READ] Fetches list of installed themes (themes/).

Returns: JSON with list of installed themes, their paths, and metadata.

[READ] Read a configuration file with optional line offset and limit.

[READ] Read a text file with allowlist validation and size limits.

[READ] Resolves a blueprint automation to its concrete configuration.

If the automation uses a blueprint (`use_blueprint` key), loads the blueprint YAML, substitutes user-provided input values into the template, and returns the resolved automation as if it were a regular (non-blueprint) automation. Regular automations are returned unchanged.

Resolution is computed, not persisted — the stored YAML is never modified.

[READ] Search automations by alias, description, mode, or blueprint usage. ~95% token savings vs listing all.

~95% token savings when searching for a specific automation. Instead of: list_automations() (111 items) -> search (1-5 items)

[READ] Find all automations that reference a given entity in triggers, conditions, or actions. Checks if entity is in triggers, conditions, or actions.

[READ] Search YAML configuration files by structured parameters (entity_id, service, platform, device_class).

[READ] Search config entries with optional filters.

[READ] Searches devices with filtering.

[READ] Search entities by name or entity_id.

[READ] Searches entities by name or entity_id in the registry.

Warning: Use search_registries_batch() for more advanced searching.

[READ] Search for files containing a text pattern (safe grep).

[READ] Searches for a specific phrase in all configuration files.

[READ] Search for multiple text phrases across many config files simultaneously.

[READ] Searches inside automation YAML for a pattern across triggers, conditions, or actions.

Searches within YAML dump of each automation for the given pattern. Supports regex with safe validation.

[READ] Searches for a specific phrase in logs with optional context.

[READ] Search inside Lovelace dashboard configurations by entity_id, card_type, or free-text.

Searches cards/badges across all dashboards by entity_id, card_type, or free-text search_term. ~90% token savings vs returning full configs.

[READ] Search multiple registries (entity, device, area) simultaneously by name, entity_ids, area, device, or platform. ~85% token savings.

Instead of: get_entity_registry() + get_device_registry() + filter × N

[READ] Take a snapshot of current entity health (unavailable entities grouped by integration) for later comparison.

Args: (none)

Returns: JSON with snapshot_id, total_entities, unavailable_count, and unavailable_by_integration.

[READ] Generate system health report (read-only). Returns JSON with metrics, logs, entity and automation health.

Returns: JSON with health score, system metrics, log summary, entity health, automation health, and generation timestamp.

[READ] Validate automation alias naming conventions against 7 quality rules.

Checks each automation alias for separator style, canonical prefix, Polish characters, emoji, title case, compound hyphens, and version casing.

[READ] Validate multiple YAML files in one call. Saves ~80% tokens vs individual calls.

[READ] Pre-deployment check: validates YAML syntax and checks references to entities/services/templates.

[READ] Quick verification of recent changes in the Home Assistant system. ~85% token savings for questions about new entities or recent automation runs.