Uses .env files for configuration management, storing connection details and authentication tokens for Home Assistant integration.
Provides tools for querying and controlling Home Assistant entities through natural language, including state management, service calls, historical data access, and device control in a smart home environment.
Provides specific installation and configuration paths for macOS systems when integrating with Claude Desktop.
Home Assistant MCP Server
A Model Context Protocol (MCP) server for integrating with Home Assistant, allowing LLMs to control and query your smart home.
Features
Query and control Home Assistant entities via natural language
Works with any MCP-compatible client (like Claude Desktop)
Provides tools for state management, service calls, history, and more
Secure authentication using Home Assistant long-lived access tokens
Multiple transport options (stdio for local processes, SSE for remote clients)
Demo mode with mock data for testing and demonstration when Home Assistant is not available
Related MCP server: Home Assistant MCP Server
Installation
Configuration
Create a .env file in your current directory with the following variables:
Environment Variables
Variable | Required | Default | Description |
| Yes | - | URL to your Home Assistant instance (e.g., http://homeassistant.local:8123 ) |
| Yes | - | Long-lived access token for authenticating with Home Assistant |
| No | 3000 | Port number for the HTTP server when using HTTP/SSE transport |
| No | false | When set to "true", enables mock data mode for testing without a Home Assistant connection |
To get a long-lived access token:
Log in to your Home Assistant instance
Click on your profile (bottom left)
Scroll down to "Long-Lived Access Tokens"
Create a new token with a descriptive name
Copy the token value (you won't see it again)
Usage
Running as a standalone server
Integration with Claude Desktop
To use with Claude Desktop:
Edit your Claude Desktop config file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Add the server configuration:
If you have Home Assistant running, simply remove the --mock flag and set HASS_MOCK to false.
Restart Claude Desktop
Available Tools
The server exposes several tools for interacting with Home Assistant:
states- Query entity stateslights- List lightslight- Control a lightservice- Call Home Assistant serviceshistory- Retrieve historical entity dataservices- List available servicesconfig- Get Home Assistant configurationdomains- List available domainserror_log- Get Home Assistant error logdevices- Get all devices in Home Assistant
For detailed usage examples, see docs/hass-mcp.md.
Security
This server requires a Home Assistant access token with full access. Consider these security recommendations:
Only run the server on trusted networks
Use HTTPS if exposing the server remotely
Keep your
.envfile secure and don't commit it to source controlConsider using a token with limited permissions when possible
License
This project is licensed under the MIT License - see the LICENSE file for details.