Labsco
MCP SERVER

Ha MCP Readonly

by paulomac1000 ↗

Full observability over a Home Assistant install — automations, blueprints, devices, logs, dashboards, dependency graph — with no write path of any kind.

IoT, Smart Home & Embedded Hardware✓ Verified
Summary
Built to answer "why did that automation fire", not to flip a switch.

The read-only boundary is the design, not a limitation: an assistant with this attached can read your YAML, correlate it with the logs, and trace which entity broke which dashboard, while being structurally unable to change anything it finds. The catalogue is 145 read-only tools by default and 158 with developer tools enabled via `MCP_DEV_TOOLS_ENABLED`, so on a client with a tight tool budget you will want to attach it selectively. Tool responses carry a `success` field — check it before reading `data`.

What it is

A read-only MCP server for Home Assistant, built for the debugging half of running a smart home rather than the controlling half. It reads entity states, automation and script YAML, blueprints, registries, logs and Lovelace dashboards, and it cannot change state, call a service or trigger an automation. A separate context generator writes the same picture out as a bounded Markdown snapshot for retrieval systems and AI project knowledge.

What you get
  • Entity states looked up, grouped, searched and summarised across the whole install — `get_entity_state`, `get_states_grouped`, `search_entities`, `get_system_overview`
  • Automations read as code with their file location, diagnosed, searched by the entity they touch, and checked against each other for conflicts — `list_automations`, `get_automation_code`, `diagnose_automation`, `search_automations_by_entity`, `get_automation_conflicts`
  • Scripts, scenes and blueprints listed and read, including which automations a blueprint produced — `list_scripts`, `get_script_code`, `list_scenes`, `get_blueprint_code`, `get_blueprint_instances`, `resolve_blueprint_automation`
  • Devices, areas, config entries and integrations inspected and diagnosed — `get_device_details`, `get_devices_by_area`, `diagnose_config_entry`, `get_integration_health`
  • Logs turned into findings rather than pages: error analysis, startup errors, a timeline, and free-text search — `get_log_insights`, `analyze_log_errors`, `get_startup_errors`, `get_log_timeline`, `search_logs`
  • Dependency direction on any entity — what it depends on, what consumes it, and the context chain around it — `get_entity_dependencies`, `get_entity_consumers`, `entity_get_context_tree`, `get_context_chain`
  • A semantic graph of the install that finds references, scores blast radius, detects ghost references and orphans, and exports to Mermaid — `graph_build_index`, `graph_find_references`, `graph_entity_impact`, `graph_detect_ghost_references`, `graph_detect_orphans`, `graph_export_mermaid`
  • Configuration files read, searched and YAML-validated, and Lovelace dashboards and resources dumped and diagnosed — `read_config_file`, `search_in_config`, `validate_yaml_syntax`, `get_lovelace_config`, `diagnose_lovelace_setup`
  • Batch and composite calls that replace a dozen round trips: bulk entity search, state comparison, batch YAML validation, and one-shot investigations — `bulk_search_entities`, `compare_entities_state`, `validate_yaml_batch`, `investigate_entity`, `get_area_diagnostic`, `audit_config_orphans`
  • A Markdown context snapshot generated in `offline`, `online` or `hybrid` mode, each source recorded with its status, record count and redaction count in a provenance matrix
Requirements

A Home Assistant instance and a long-lived access token: `HA_URL` and `HA_TOKEN`. The filesystem tools additionally need the Home Assistant config directory reachable, pointed at by `HA_CONFIG_PATH`. The package is `ha-mcp-readonly` (2.0.0 in pyproject) on Python 3.11 or newer, or the container at `ghcr.io/paulomac1000/ha-mcp-readonly`. Stdio is the default transport and opens no network port; for Streamable HTTP set `MCP_TRANSPORT=http` and a caller token in `MCP_AUTH_TOKEN`, and keep the bind address controlled — ports 9091, 9092 and 9093 are meant for localhost or a reverse proxy, not the open internet.

Setup effort

One command plus a key — docker run -d --name ha-mcp-readonly -p 127.0.0.1:9091:9091 -p 127.0.0.1:9092:9092 -e HA_URL=http://your-ha-ip:8123 -e HA_TOKEN=your_token -e MCP_TRANSPORT=http -e MCP_BIND_HOST=0.0.0.0 -e MCP_AUTH_TOKEN=replace-with-a-high-entropy-caller-token -v /path/to/ha/config:/config:ro ghcr.io/paulomac1000/ha-mcp-readonly:latest, then supply credentials