ha

ha-mcp is a MCP server that exposes a rich set of Home Assistant focused tools to an AI client via HTTP/WebSocket. It enables you to query entities, manage automations, scripts, and scenes, inspect registries, analyze dependencies, and perform system administration tasks such as config validation and logbook access. The server is designed to work with an external Home Assistant instance, granting AI assistants the ability to read data and perform CRUD operations on Home Assistant resources through a structured MCP interface. You can connect your AI client by configuring a MCP connection entry that points to the ha-mcp instance and includes proper authentication headers or tokens as required by your deployment.

Prerequisites:

• Docker installed and running on the host
• Access to a Home Assistant URL and a long-lived access token

Install and run the MCP server (Docker):

1. Pull and run the image in detached mode, exposing the MCP port (default 8080):

docker run -d --name ha-mcp -p 8080:8080 \
  -e HA_URL=http://homeassistant.local:8123 \
  -e HA_TOKEN=your-long-lived-token \
  zorak1103/ha-mcp:latest

2. Verify the container is running:

docker ps | grep ha-mcp

3. If you need to stop/remove later:

docker stop ha-mcp
docker rm ha-mcp

Alternative install method if you prefer binary or Go-based builds can be found in the repository releases, but using the Docker image is the recommended approach for quick setup.

• Ensure the Home Assistant URL (HA_URL) and token (HA_TOKEN) are provided and valid; the MCP server relies on these to access Home Assistant data.
• The server exposes port 8080 by default; configure your client to connect to http://<host>:8080.
• For production, consider enabling TLS/HTTPS and WebSocket security as appropriate for your environment.
• You can adjust environment variables and Docker options to fit your deployment (restart policies, logging drivers, network settings).
• If you need more contained setups, you can also build and run the binary directly from source or use other supported deployment methods described in the docs.