homeassistant

This MCP server exposes a production-ready REST API for full control of Home Assistant. It provides 97 unified endpoints that cover core Home Assistant functionality, including entity states, services, events, device and area discovery, automations, dashboards, and much more. The server speaks REST over HTTP with Pydantic-validated requests and responses, and also supports WebSocket operations for real-time updates and a responsive UI experience. Authentication is handled automatically by injecting the SUPERVISOR_TOKEN from Home Assistant's environment, so you can rely on secure access within supported environments. You can explore the API via the interactive OpenAPI/Swagger docs at the configured host and port, and you can integrate the MCP server into AI assistants or automation platforms using standard HTTP calls or the MCP protocol (MCPO).

Prerequisites:\n- A Home Assistant OS or Supervised installation (with Supervisor) and a running instance.\n- Python 3.x environment available on the MCP host (the server runs as a Python FastAPI app via Uvicorn).\n- Network access to your Home Assistant instance (default port 8001 for the API).\n\nStep-by-step installation:\n1) Ensure Python and pip are installed on the host where you will run the MCP server.\n2) Install or pull the Home Assistant OpenAPI Server MCP package from your preferred source (the MCP package exposes an entry point ha_openapi_server). For example:\n\n # If distributing via pip or a local package, install as usual:\n pip install ha-openapi-server\n\n3) Run the MCP server using Python:\n\n python -m ha_openapi_server\n\n4) Verify the server is running by checking logs and accessing the API documentation:\n - Swagger UI: http://<host>:8001/\n - OpenAPI spec: http://<host>:8001/openapi.json\n - Health: http://<host>:8001/health\n\n5) Ensure the Home Assistant SUPERVISOR_TOKEN is accessible by the server (the addon handles this automatically when deployed as an addon in Home Assistant).

Tips and notes:\n- The API authenticates via the SUPERVISOR_TOKEN injected by the Home Assistant environment; ensure you’re running in a host context where this token is available.\n- Use the OpenAPI spec to discover endpoints and request schemas, which is helpful when integrating with AI tools or MCP clients.\n- The server is designed to be run as a lightweight integration addon or standalone MCP host; adjust network binding (host/port) as needed for your deployment.\n- If you encounter 401 Unauthorized, confirm the addon/service is started and the SUPERVISOR_TOKEN is detectable by the process.\n- WebSocket support enables real-time dashboards and Lovelace operations; consider using a client that can handle WebSocket updates for a responsive UI.\n- Ensure your Home Assistant version is 2025.11+ as indicated by the integration requirements.