home-assistant

This MCP server provides a bridge between large language models and your Home Assistant instance. It exposes a set of tools that let you query and control Home Assistant entities using natural language, including querying states, listing lights and devices, calling services, retrieving history, and more. The server supports multiple transport options (HTTP/SSE for remote clients and stdio for local process communication) and includes a demo mode that uses mock data when Home Assistant is unavailable. You can use the server with any MCP-compatible client (for example Claude Desktop) to issue natural language commands that map to Home Assistant actions.

To use the server, configure the environment with your Home Assistant URL and a long-lived access token. Run the server in HTTP/SSE mode to enable remote clients, or use stdio for direct inter-process communication. If you want to test without a live Home Assistant, enable the mock mode via HASS_MOCK. The server exposes tools such as states, lights, light, service, history, services, config, domains, error_log, and devices, which you can leverage in your prompts or tool calls to perform specific actions against Home Assistant.

Prerequisites:

• Node.js (or Bun) installed on your system
• Access to your Home Assistant instance with a long-lived access token
• Optional: Git for cloning the repository

Installation steps:

1. Install globally using Bun (preferred for this project):

bun install -g home-assistant-mcp-server

2. 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

3. Run the server (example for HTTP/SSE transport):

home-assistant-mcp-server

4. If you need stdio transport for direct process communication:

home-assistant-mcp-server --stdio

5. Optional: run in mock/demo mode (no live Home Assistant required):

home-assistant-mcp-server --mock

Configuration (environment variables):

• Create a .env file in your working directory with the following variables:

HASS_URL=http://your-home-assistant:8123
HASS_TOKEN=your_long_lived_access_token
PORT=3000
HASS_MOCK=false

Notes:

• Replace HASS_URL with your Home Assistant instance URL and HASS_TOKEN with a valid token.
• If you run in mock mode, you can still test the MCP interface without a live HA instance.

Environment variables:

• HASS_URL: required when not using mock mode; URL to Home Assistant (e.g., http://home-assistant.local:8123)
• HASS_TOKEN: required for authentication with Home Assistant
• PORT: optional server port for HTTP/SSE (default 3000)
• HASS_MOCK: when set to true, enables mock data mode for testing without a live HA connection

Security tips:

• Use HTTPS when exposing the server remotely
• Keep the .env file secure and do not commit to version control
• Consider using a token with the least privileges necessary

Troubleshooting:

• If you see authentication errors, verify that HASS_TOKEN is valid and has the required permissions
• Ensure HASS_URL is reachable from the server host
• In mock mode, verify that requests still conform to the expected tool names (states, lights, service, etc.)