Server facts
Home Assistant MCP Server
Project
- Author
- tevonsb
- Repository
- github.com/tevonsb/homeassistant-mcp
- License
- Apache-2.0
- Category
- Mobile & Desktop Automation
Tech
- Runtime / language
- nodeTypeScript
- Transports
- stdio
- Remote available
- No
- Authentication
- Not specified
Activity
- GitHub stars
- 577
- Last commit
- Data as of
Tags
- Automation
- Device Control
- Home Assistant
- Smart Home
- Typescript
Overview
Home Assistant MCP Server bridges a local Home Assistant installation and language-model applications. Its documented scope ranges from changing lights, climate settings, covers, media players, and other devices to inspecting states and historical information. Automation features include creating, editing, duplicating, enabling, disabling, and manually triggering rules. System-management functions extend to add-ons and HACS packages when the corresponding Home Assistant capabilities are available. Device grouping by area and floor supplies organizational context for assistant requests.
The README describes HTTP endpoints for state, context, actions, and sequential action batches, alongside SSE subscriptions and WebSocket events for live updates. Authentication uses tokens, and rate limiting is documented for API traffic. Installation starts from a cloned repository, with npm dependency installation and a build step; Docker Compose is the recommended deployment path. Configuration points to the Home Assistant host and WebSocket endpoint and supplies a long-lived access token. Node.js 20.10 or newer is listed among prerequisites. HACS is necessary for package management, and Supervisor access is necessary for add-on operations. The Claude Desktop process configuration shown in the README is incomplete and explicitly separate from Docker usage, so the reliable reproduced launch here is the Compose command. The supplied material establishes a broad home-control bridge, but does not provide a complete Docker-to-MCP-client connection example.
Install & configure
Requirements
- A cloned homeassistant-mcp checkout
- Docker Compose
- Running Home Assistant instance
- Home Assistant long-lived access token
- HACS for package features
- Supervisor access for add-on features
docker compose up -dRun from the cloned repository after configuring its .env file. The README documents an HTTP API on http://localhost:3000 and a /health check; these are not specified as an MCP endpoint. Its process-based Claude Desktop example is incomplete and does not work with the Docker method. Node.js 20.10+ and npm are listed for source setup.
Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Use Settings → Developer → Edit Config when available. Do not assume a Linux configuration path; check the client documentation for your platform. Remote servers use the app’s connector flow when supported, not the local stdio file shown here. Merge this example with existing settings; do not overwrite unrelated servers.
No install command stated in the README — see repo. Check the client documentation for a supported connection method.
Read the Claude Desktop setup guideConfig file · Project: .cursor/mcp.json
User: ~/.cursor/mcp.json
The project path is relative to the workspace root. The tilde denotes your user home directory. Use Cursor’s MCP settings to confirm which configuration and scope your installed version is reading. Merge this example with existing settings; do not overwrite unrelated servers.
No install command stated in the README — see repo. Check the client documentation for a supported connection method.
Read the Cursor setup guideConfig file · Workspace: .vscode/mcp.json
For user scope, use the “MCP: Open User Configuration” command if available. Do not guess a user configuration path across operating systems, profiles, containers, or remote workspaces; check the client documentation. Merge this example with existing settings; do not overwrite unrelated servers.
No install command stated in the README — see repo. Check the client documentation for a supported connection method.
Read the VS Code setup guideConfig file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
Open the MCP configuration through Windsurf’s settings when possible to confirm the active file. Paths can differ in managed or future releases; check the client documentation if this location is not present. Merge this example with existing settings; do not overwrite unrelated servers.
No install command stated in the README — see repo. Check the client documentation for a supported connection method.
Read the Windsurf setup guideConfig file · Project scope: .mcp.json at the repository root
The project file uses mcpServers. For user scope, use claude mcp add --scope user rather than assuming .mcp.json in your home directory is the user configuration. Check the client documentation for managed settings and storage details. Merge this example with existing settings; do not overwrite unrelated servers.
No install command stated in the README — see repo. Check the client documentation for a supported connection method.
Read the Claude Code setup guideExamples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Tools
Source: repository README. Tool descriptions are a documented snapshot, not a live capability check.
| Tool | What it does |
|---|---|
| control | Send device commands such as toggling entities or changing light settings. |
| addon | List, install, or change the running state of Home Assistant add-ons. |
| package | List or install HACS packages by category and repository. |
| automation_config | Create, modify, or duplicate Home Assistant automation configurations. |
Names, permissions, and defaults can change. Check the current upstream documentation before granting access.
Use cases
- Adjust lights, climate, covers, or media playback conversationally.
- Monitor entity changes through event subscriptions.
- Create and modify Home Assistant automations.
- Manage HACS packages when HACS is installed.
- Administer add-ons with Supervisor access.
Strengths
- Covers device control, automation, and system administration.
- Documents SSE and WebSocket event updates.
- Includes a Docker Compose deployment path.
Limitations
- Package and add-on features need HACS and Supervisor respectively.
- Requires a Home Assistant long-lived access token.
- The supplied Claude Desktop launch example is incomplete.
Frequently asked questions
Independent listing, not an affiliation or security review. Grant the least access needed and verify the upstream instructions before running code.
