home / mcp / home assistant mcp server
A Model Context Protocol Server for Home Assistant
Configuration
View docs{
"mcpServers": {
"allenporter-mcp-server-home-assistant": {
"command": "uv",
"args": [
"run",
"mcp-server-home-assistant",
"-v",
"-v"
],
"env": {
"HOME_ASSISTANT_API_TOKEN": "byJhbVci0iJIUzI1ii1sInR5cCI6IkpXVCJ9.....",
"HOME_ASSISTANT_WEB_SOCKET_URL": "http://localhost:8123/api/websocket"
}
}
}
}You run an MCP server that lets your assistant communicate with Home Assistant by exposing a dedicated runtime endpoint. This lets you perform Home Assistant actions and fetch data through the Model Context Protocol, keeping your integrations modular and extensible.
To connect your MCP client to the Home Assistant integration, configure a Home Assistant MCP server with the provided runtime and environment variables. Start the server, then point your MCP client at it to enable seamless control and data access from Home Assistant.
Use the following configuration to run the Home Assistant MCP server. This starts the server in verbose mode and passes the required Home Assistant WebSocket URL and API token through environment variables.
{
"mcpServers": {
"Home-assistant": {
"command": "uv",
"args": [
"run",
"mcp-server-home-assistant",
"-v",
"-v"
],
"env": {
"HOME_ASSISTANT_WEB_SOCKET_URL": "http://localhost:8123/api/websocket",
"HOME_ASSISTANT_API_TOKEN": "byJhbVci0iJIUzI1ii1sInR5cCI6IkpXVCJ9....."
}
}
}
}Prerequisites you need to prepare before starting the MCP server include a running Home Assistant instance and a Long-Lived Access Token for API access. You will also run the MCP server using the uv runtime as shown in the example configuration.
Step 1. Clone the MCP server repository to a local path of your choice.
Step 2. Ensure the uv runtime is available on your system. This will be used to execute the MCP server binary and its arguments.
Step 3. Create a Long Lived Access Token in Home Assistant to authorize API access.
Step 4. Prepare the configuration snippet exactly as shown in the example and save it to use with your MCP client.
Step 5. Start the MCP server using the command and environment variables defined in your configuration.
Notes about security: keep your Home Assistant API token secret and rotate tokens periodically. If you run multiple MCP servers, assign unique names (in lowercase and with underscores) to avoid conflicts.
Logging: you can monitor server activity in your environment logs to understand startup progress, token validation, and WebSocket handshakes. Check the log files for any errors during initialization.