Homeassistant MCP

What tevonsb/homeassistant-mcp MCP server does

The tevonsb/homeassistant-mcp MCP server gives an LLM application access to a local Home Assistant installation through MCP. It covers common smart-home operations such as switching lights and switches, adjusting climate settings, moving covers, controlling media players, fans, locks, and vacuums, and reading sensor or contact states. Camera-related capabilities include motion detection and snapshots as described by the project.

Beyond individual devices, the server supports Home Assistant administration tasks. Agents can query and monitor states, work with areas and floors, create or edit automations, enable or disable them, trigger them manually, and modify existing rules. Add-on operations include browsing, installing, removing, starting, stopping, restarting, and managing versions or configuration. HACS-related operations cover custom integrations, themes, Python scripts, AppDaemon apps, and NetDaemon apps.

How it works

The application communicates with Home Assistant using its HTTP host configuration and WebSocket URL, authenticating with a long-lived Home Assistant access token. MCP provides the interface used by the LLM client, while the server handles Home Assistant API access and validation.

A separate Server-Sent Events endpoint provides live updates. Clients can subscribe to state changes, automation triggers and executions, service calls, or script executions. Subscriptions can be narrowed to a domain or entity, making the stream useful for agents that need current device context instead of repeated polling.

Setup and configuration

To run the tevonsb/homeassistant-mcp MCP server from source, use Node.js 20.10.0 or newer and npm. Clone the repository, install dependencies with npm install, and build it with npm run build. The project also includes Docker support; after creating an environment file, start it with Docker Compose and check the /health endpoint on the configured port.

Set HASS_HOST to the Home Assistant URL, HASS_TOKEN to a long-lived access token, and HASS_SOCKET_URL to the Home Assistant WebSocket endpoint. PORT defaults to 3000, while NODE_ENV and DEBUG control runtime behavior. The repository also documents separate environment files for development, production, and testing.

Claude Desktop can run the built server directly through a client configuration that supplies the Node command and environment variables. The README specifically notes that this direct client setup is separate from the Docker deployment method.

Tools and capabilities

Supported areas include:

• Controlling lights, climate devices, covers, switches, media players, fans, locks, and vacuums.
• Reading states from sensors, contacts, cameras, and other Home Assistant entities.
• Creating, editing, duplicating, enabling, disabling, and manually triggering automations.
• Browsing and managing Home Assistant add-ons.
• Managing HACS packages and supported package types.
• Receiving filtered real-time events through SSE.

The API examples show a general control operation with commands such as turn_on, turn_off, and toggle, plus light parameters for brightness, color temperature, and RGB color.

Limitations and notes

A running Home Assistant instance is required. The project lists a long-lived access token as a prerequisite. HACS must be installed for package-management features, and Supervisor access is required for add-on management. These administrative capabilities may therefore be unavailable in installations without those Home Assistant components or permissions.

The documented Docker deployment exposes the service on port 3000 by default. SSE clients need an HTTP-capable connection and must provide the configured token when subscribing.