Home Assistant MCP Server

How to use

You operate the server with a local MCP client or via a remote client that supports MCP. Start the server in stdio mode for direct process communication, or run it with HTTP/SSE transport to connect over a network. The server authenticates to Home Assistant using a long-lived access token and reads the Home Assistant URL from your environment. Use the client to ask it to query states, list entities, control lights, trigger services, fetch history, and more. If Home Assistant isn’t available, you can start the server in mock mode to demonstrate capabilities without a live connection.

How to install

Prerequisites: you need a recent Node.js-compatible runtime or Bun for dependency management and building. You’ll also need a Home Assistant instance and a long-lived access token.

# Install prerequisites (example with Bun)
# Ensure Bun is installed on your system
# Bun installs dependencies and builds the project globally
bun install -g home-assistant-mcp-server

# Or install from source
git clone https://github.com/oleander/home-assistant-mcp-server.git
cd home-assistant-mcp-server
bun install
bun run build
bun link

# Run in HTTP/SSE mode (default) or stdio mode as needed
home-assistant-mcp-server
home-assistant-mcp-server --stdio

Configuration and security

Create a .env file in your working directory to provide the connection details to Home Assistant and control how the server runs. You must supply the Home Assistant URL and a long-lived access token. Optional settings let you choose the listening port and enable mock data for testing.

# Required configurations
HASS_URL=http://your-home-assistant:8123  # URL to your Home Assistant instance
HASS_TOKEN=your_long_lived_access_token   # Long-lived access token for authentication

# Optional configurations
PORT=3000                # Port for the HTTP server (default: 3000)
HASS_MOCK=false          # Enable mock data mode when Home Assistant is unavailable (default: false)

Usage with Claude Desktop

To integrate with Claude Desktop, provide the MCP server configuration in your Claude setup so it can start and talk to the MCP server. Include the server command and the authentication details you defined in the environment variables.

{
  "mcpServers": {
    "homeassistant": {
      "command": "home-assistant-mcp-server",
      "env": {
        "HASS_URL": "http://your-home-assistant:8123",
        "HASS_TOKEN": "your_token_here",
        "HASS_MOCK": "true"
      }
    }
  }
}

Notes and troubleshooting

If you have Home Assistant running, you can remove the mock flag and set HASS_MOCK to false to connect to the real instance. Keep your .env file secure and avoid committing it to version control. For local testing, mock data mode is convenient but not a substitute for a live Home Assistant connection.

states

Query entity states across your Home Assistant setup to get current values and statuses.

lights

List available lights and their current state for quick discovery.

light

Control a specific light, including turning on/off and adjusting brightness or color if supported.

service

Call Home Assistant services to perform actions such as turning on a scene or starting a automation.

history

Retrieve historical data for entities to analyze trends and usage over time.

services

List available Home Assistant services for quick reference.

config

Fetch Home Assistant configuration details for debugging and validation.

domains

List available domains to explore supported entity types.

error_log

Get Home Assistant error logs to diagnose issues.

devices

Retrieve all devices registered in Home Assistant.