Home Assistant MCP Server

What is Home Assistant MCP Server?

This Home Assistant MCP server is a community-built Node.js server by tevonsb that gives an LLM access to your local Home Assistant instance. It can control and monitor devices, manage automations, add-ons and HACS packages, and stream real-time updates.

It is written in TypeScript, connects to Home Assistant with a long-lived access token, and can run from source or in Docker. It is not the official integration: Home Assistant now ships its own built-in Model Context Protocol Server integration, compared below.

How to use Home Assistant MCP Server?

Prerequisites:

• Node.js 20.10.0 or higher, and npm
• A running Home Assistant instance and a long-lived access token
• Optional: Docker Compose, HACS (for package management) and Supervisor access (for add-on management)

Install from source:

git clone https://github.com/tevonsb/homeassistant-mcp.git
cd homeassistant-mcp
npm install
npm run build

Configure a .env file (copy .env.example):

HASS_HOST=http://homeassistant.local:8123
HASS_TOKEN=your_home_assistant_token
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
PORT=3000
NODE_ENV=production
DEBUG=false

Claude Desktop

Point Claude Desktop at the built dist entry and pass the same variables. The README notes that this mode runs the MCP server inside Claude and does not use the Docker setup.

{
  "mcpServers": {
    "homeassistant": {
      "command": "node",
      "args": ["/path/to/homeassistant-mcp/dist/index.js"],
      "env": {
        "NODE_ENV": "development",
        "HASS_HOST": "http://homeassistant.local:8123",
        "HASS_TOKEN": "your_home_assistant_token",
        "HASS_SOCKET_URL": "ws://homeassistant.local:8123/api/websocket",
        "PORT": "3000",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Cursor and VS Code

These are not covered in the README. As a stdio server, the same node /path/to/homeassistant-mcp/dist/index.js command and env values can be added to .cursor/mcp.json or .vscode/mcp.json.

Docker

The README recommends Docker Compose for running the HTTP server:

cp .env.example .env
docker compose up -d

The server listens on http://localhost:3000, with a health check at /health.

Key features of Home Assistant MCP Server

• Device control for lights (brightness, color temperature, RGB), climate, covers, switches, fans, locks, vacuums, media players and cameras.
• State monitoring and querying, with area- and floor-based grouping and history access.
• Real-time updates over Server-Sent Events (SSE), filtered by domain or entity.
• Automation management: create, edit, duplicate, enable or disable, and manually trigger automations with complex triggers and conditions.
• Add-on management through Supervisor: browse, install, uninstall, start, stop and restart.
• HACS package management for custom integrations, themes, Python scripts, AppDaemon and NetDaemon apps.
• Token-based authentication, rate limiting and Docker support.

Home Assistant MCP Server tools

The server registers a compact set of action-style tools:

• Devices and state: list_devices lists available devices, and control runs commands such as turn_on, turn_off or toggle on an entity_id, with extras like brightness or rgb_color for lights. get_history reads past states.
• Automations and scenes: automation manages existing automations, automation_config creates, updates or duplicates them, and scene manages and activates scenes.
• System management: addon handles Supervisor add-ons (list, install, start, stop, restart), and package installs and lists HACS packages by category.
• Events and notifications: subscribe_events and get_sse_stats cover the SSE stream, and notify sends notifications.

Use cases of Home Assistant MCP Server

• Natural-language device control: "Turn on the living room lights at 50% brightness and set them to warm white."
• Climate tweaks: "Set the thermostat to 21 degrees and switch the HVAC to heat."
• Build automations by describing them: "Create an automation that turns on the hallway light when motion is detected."
• Check the house: "Which doors and locks are open right now?"
• Maintain the system: "List installed add-ons and restart the File editor add-on," or "Install this HACS integration."
• Stream state changes over SSE to watch automations fire in real time.

Home Assistant MCP Server vs alternatives

The official Model Context Protocol Server integration is built into Home Assistant. You enable it under Settings > Devices & services, and it exposes an MCP endpoint with OAuth 2.0 + PKCE. Claude Code connects with claude mcp add --transport http home-assistant <your_mcp_server_url> followed by claude mcp login home-assistant. It only exposes entities you share with assistants, and by default it requires an administrator account. Cloud-based clients such as Claude need your instance to be reachable from the internet. For most users the official integration is the simpler, supported choice. This community server adds add-on, HACS and automation-editing tools that go beyond the official LLM APIs. Several other community Home Assistant MCP servers also exist.

Troubleshooting Home Assistant MCP Server

• toSorted is not a function: your Node.js is too old. Upgrade to 20.10.0 or newer (for example nvm install 20.10.0).
• Connection issues: verify Home Assistant is running, that HASS_HOST is reachable from the machine running the server, and that the token has the right permissions. Check HASS_SOCKET_URL for real-time updates.
• Add-on tools fail: add-on management needs Supervisor access, so verify it is available on your installation and check add-on compatibility.
• HACS tools fail: confirm HACS is installed and its integration is working.
• Automation errors: check that the referenced entities exist, review trigger conditions and service calls, and watch the logs.