AHA

You run an MCP server that bridges Home Assistant with MCP clients, allowing you to query entities, manage automations, call services, and work with dashboards through multiple transport options such as STDIO, SSE, and HTTP. This guide walks you through practical usage, installation steps, and key configuration details so you can connect your MCP clients and start automating today.

How to use

You interact with the AHA MCP Server by starting it in one of several transport modes and then configuring your MCP client to connect. The server exposes a set of endpoints and tools that let you list and query Home Assistant entities, retrieve and update states, call services, manage automations, access registries, and work with Lovelace dashboards. Use the STDIO path when your MCP client launches the server, or use SSE/HTTP transport when you host the server separately and point clients to its URL.

How to install

Prerequisites: Node.js v18 or newer and Docker if you want containerized deployment.

Step 1: Install dependencies.

npm install

Step 2: Run the server in the desired transport mode. Use the provided commands and environment variables to configure access to Home Assistant.

Environment and transport overview

The server supports STDIO, SSE, and Streamable HTTP transports. Environment variables control access to Home Assistant and debugging features. The transport mode is chosen by the run command you execute.

Server connection configurations

You can connect clients using either a local STDIO command or a remote HTTP/SSE endpoint. The following configurations illustrate the two main approaches shown in practical setups.

Additional notes and tips

If you enable RESOURCES_TO_TOOLS, Home Assistant resources such as entities and automations can be exposed as discrete MCP tools. This helps clients that operate via tool interfaces discover and use features directly. Debug logging can be turned on with DEBUG=true to help troubleshoot transport or authentication issues.

Configuration and troubleshooting

Make sure you supply a valid Home Assistant URL and a long-lived access token. If you switch transports, ensure the server is started separately for SSE/HTTP modes and that your client points to the correct URL (for SSE: /sse, for HTTP: /mcp). If you encounter permission or connection errors, verify that HASS_URL and HASS_ACCESS_TOKEN are correctly set and that network access to your Home Assistant instance is allowed from the MCP server host.

Available tools

Automation Management

Create, update, delete, and trace automations within Home Assistant via MCP endpoints.

Entity Operations

Query and manipulate Home Assistant entities, including listing, searching, and filtering.

Service Calls

Execute Home Assistant services to control devices and entities.

Configuration

Validate and manage Home Assistant configuration from MCP clients.

Registry Access

Access entity and device registries for inspection and management.

Lovelace Dashboard

Integrate and update Lovelace dashboards in Home Assistant.

Config Entry Flow Helpers

Create and manage Home Assistant integration configuration flows.