Skip to content
Back to search

hass-mcp

Control and query Home Assistant from Claude and other LLMs — a Model Context Protocol (MCP) server.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/voska--hass-mcp/badge.svg)](/listings/voska--hass-mcp)

HTML

<a href="/listings/voska--hass-mcp"><img src="/api/listings/voska--hass-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Pull the Docker image:

   docker pull voska/hass-mcp:latest

2. Add the MCP server to Claude Desktop:

a. Open Claude Desktop and go to Settings b. Navigate to Developer > Edit Config c. Add the following configuration to your `claude_desktop_config.json` file:

   {
     "mcpServers": {
       "hass-mcp": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-e",
           "HA_URL",
           "-e",
           "HA_TOKEN",
           "voska/hass-mcp"
         ],
         "env": {
           "HA_URL": "http://homeassistant.local:8123",
           "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
         }
       }
     }
   }

d. Replace `YOUR_LONG_LIVED_TOKEN` with your actual Home Assistant long-lived access token e. Update the `HA_URL`:

- If running Home Assistant on the same machine: use `http://host.docker.internal:8123` (Docker Desktop on Mac/Windows) - If running Home Assistant on another machine: use the actual IP or hostname

f. Save the file and restart Claude Desktop

3. The "Hass-MCP" tool should now appear in your Claude Desktop tools menu

> **Note**: If you're running Home Assistant in Docker on the same machine, you may need to add `--network host` to the Docker args for the container to access Home Assistant. Alternatively, use the IP address of your machine instead of `host.docker.internal`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 341 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Hass-MCP
  2. [![MCP Toplist](https://mcptoplist.com/badge/glama%2Fvoska%2Fhass-mcp.svg)](https://mcptoplist.com/server/glama%2Fvoska%2Fhass-mcp)
  3. A Model Context Protocol (MCP) server for Home Assistant integration with Claude and other LLMs.
  4. <a href="https://glama.ai/mcp/servers/@voska/hass-mcp">
  5. <img width="380" height="200" src="https://glama.ai/mcp/servers/@voska/hass-mcp/badge" alt="Hass-MCP MCP server" />
  6. </a>
  7. ## Overview
  8. Hass-MCP enables AI assistants like Claude to interact directly with your Home Assistant instance, allowing them to:
  9. - Query the state of devices and sensors
  10. - Control lights, switches, and other entities
  11. - Get summaries of your smart home
  12. - Troubleshoot automations and entities
  13. - Search for specific entities
  14. - Create guided conversations for common tasks
  15. ## Screenshots
  16. <img width="700" alt="Screenshot 2025-03-16 at 15 48 01" src="https://github.com/user-attachments/assets/5f9773b4-6aef-4139-a978-8ec2cc8c0aea" />
  17. <img width="400" alt="Screenshot 2025-03-16 at 15 50 59" src="https://github.com/user-attachments/assets/17e1854a-9399-4e6d-92cf-cf223a93466e" />
  18. <img width="400" alt="Screenshot 2025-03-16 at 15 49 26" src="https://github.com/user-attachments/assets/4565f3cd-7e75-4472-985c-7841e1ad6ba8" />
  19. ## Features
  20. - **Entity Management**: Get states, control devices, and search for entities
  21. - **Domain Summaries**: Get high-level information about entity types
  22. - **Automation Support**: List and control automations
  23. - **Guided Conversations**: Use prompts for common tasks like creating automations
  24. - **Smart Search**: Find entities by name, type, or state
  25. - **Live Dashboard Editing**: Read and edit Lovelace dashboards (cards and views) over Home Assistant's WebSocket API — changes appear instantly in open browsers, with automatic backups and a dry-run preview
  26. - **Token Efficiency**: Lean JSON responses to minimize token usage
  27. ## Installation
  28. ### Prerequisites
  29. - Home Assistant instance with Long-Lived Access Token
  30. - One of the following:
  31. - Docker (recommended)
  32. - Python 3.13+ and [uv](https://github.com/astral-sh/uv)
  33. ## Setting Up With Claude Desktop
  34. ### Docker Installation (Recommended)
  35. 1. Pull the Docker image:
  36. ```bash
  37. docker pull voska/hass-mcp:latest
  38. ```
  39. 2. Add the MCP server to Claude Desktop:
  40. a. Open Claude Desktop and go to Settings
  41. b. Navigate to Developer > Edit Config
  42. c. Add the following configuration to your `claude_desktop_config.json` file:
  43. ```json
  44. {
  45. "mcpServers": {
  46. "hass-mcp": {
  47. "command": "docker",
  48. "args": [
  49. "run",
  50. "-i",
  51. "--rm",
  52. "-e",
  53. "HA_URL",
  54. "-e",
  55. "HA_TOKEN",
  56. "voska/hass-mcp"
  57. ],
  58. "env": {
  59. "HA_URL": "http://homeassistant.local:8123",
  60. "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
  61. }
  62. }
  63. }
  64. }
  65. ```
  66. d. Replace `YOUR_LONG_LIVED_TOKEN` with your actual Home Assistant long-lived access token
  67. e. Update the `HA_URL`:
  68. - If running Home Assistant on the same machine: use `http://host.docker.internal:8123` (Docker Desktop on Mac/Windows)
  69. - If running Home Assistant on another machine: use the actual IP or hostname
  70. f. Save the file and restart Claude Desktop
  71. 3. The "Hass-MCP" tool should now appear in your Claude Desktop tools menu
  72. > **Note**: If you're running Home Assistant in Docker on the same machine, you may need to add `--network host` to the Docker args for the container to access Home Assistant. Alternatively, use the IP address of your machine instead of `host.docker.internal`.
  73. ### uv/uvx
  74. 1. Install uv on your system.
  75. 2. Add the MCP server to Claude Desktop:
  76. a. Open Claude Desktop and go to Settings
  77. b. Navigate to Developer > Edit Config
  78. c. Add the following configuration to your `claude_desktop_config.json` file:
  79. ```json
  80. {
  81. "mcpServers": {
  82. "hass-mcp": {
  83. "command": "uvx",
  84. "args": ["hass-mcp"],
  85. "env": {
  86. "HA_URL": "http://homeassistant.local:8123",
  87. "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN"
  88. }
  89. }
  90. }
  91. }
  92. ```
  93. d. Replace `YOUR_LONG_LIVED_TOKEN` with your actual Home Assistant long-lived access token
  94. e. Update the `HA_URL`:
  95. - If running Home Assistant on the same machine: use `http://host.docker.internal:8123` (Docker Desktop on Mac/Windows)
  96. - If running Home Assistant on another machine: use the actual IP or hostname
  97. f. Save the file and restart Claude Desktop
  98. 3. The "Hass-MCP" tool should now appear in your Claude Desktop tools menu
  99. ## Other MCP Clients
  100. ### Cursor
  101. 1. Go to Cursor Settings > MCP > Add New MCP Server
  102. 2. Fill in the form:
  103. - Name: `Hass-MCP`
  104. - Type: `command`
  105. - Command:
  106. ```
  107. docker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN voska/hass-mcp
  108. ```
  109. - Replace `YOUR_LONG_LIVED_TOKEN` with your actual Home Assistant token
  110. - Update the HA_URL to match your Home Assistant instance address
  111. 3. Click "Add" to save
  112. ### Claude Code (CLI)
  113. To use with Claude Code CLI, you can add the MCP server directly using the `mcp add` command:
  114. **Using Docker (recommended):**
  115. ```bash
  116. claude mcp add hass-mcp -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN -- docker run -i --rm -e HA_URL -e HA_TOKEN voska/hass-mcp
  117. ```
  118. Replace `YOUR_LONG_LIVED_TOKEN` with your actual Home Assistant token and update the HA_URL to match your Home Assistant instance address.
  119. ## HTTP Transport (Streamable)
  120. For deployments that can't use stdio — running behind an MCP gateway, hosting on Smithery, sharing one server across multiple clients, or connecting from network-based tools like LibreChat or OpenWebUI — Hass-MCP supports the MCP [streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports). The server runs in stateless mode (no `Mcp-Session-Id`, JSON responses), suitable for horizontally-scaled hosts.
  121. > [!CAUTION]
  122. > **HTTP mode exposes full Home Assistant control over the network.** Anyone who can reach the port can call any tool — turn off lights, unlock doors, trigger automations, restart HA. The MCP spec does not yet ship a built-in auth layer in this server. Until it does, you **must** put it behind one of:
  123. >
  124. > - A reverse proxy (nginx, Caddy, Traefik) doing basic-auth or bearer-token validation
  125. > - A VPN or zero-trust network (Tailscale, WireGuard, Cloudflare Access)
  126. > - Localhost binding only (the default — change `--host` only if you know what you're doing)
  127. >
  128. > Do not expose `:8000` to the open internet without auth.
  129. ### Running locally
  130. **Using uvx:**
  131. ```bash
  132. HA_URL=http://homeassistant.local:8123 \
  133. HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
  134. uvx hass-mcp --http --port 8000
  135. ```
  136. The server binds `127.0.0.1` by default. Override with `--host 0.0.0.0` only when you've also configured auth in front of it.
  137. ### Running in Docker
  138. ```bash
  139. docker run --rm -p 8000:8000 \
  140. -e HA_URL=http://homeassistant.local:8123 \
  141. -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
  142. voska/hass-mcp:latest --http --host 0.0.0.0 --port 8000
  143. ```
  144. `--host 0.0.0.0` is required inside Docker so the port is reachable through the bridge. Bind the publish (`-p`) to `127.0.0.1:8000:8000` if you only want it reachable from the host, or put a reverse proxy in front.
  145. ### Endpoint
  146. The MCP endpoint is at `/mcp`. Point your client at `http://<host>:<port>/mcp`.
  147. ### Smithery / PaaS
  148. The server honors the `PORT` environment variable (Smithery's convention) in addition to `MCP_PORT`. Smithery deployment requires `--http` mode and reads `PORT` automatically.
  149. ## Custom / private CA
  150. If your Home Assistant instance serves a certificate signed by your own CA (step-ca, smallstep, homelab OpenSSL), hass-mcp can verify it without disabling TLS:
  151. - **Locally**: install the CA root in your OS trust store (macOS Keychain, Windows Cert Store, or `update-ca-certificates` on Linux). hass-mcp picks it up automatically via [truststore](https://truststore.readthedocs.io/).
  152. - **In Docker** (or any sandboxed runtime): bind-mount the CA file and point `SSL_CERT_FILE` at it.
  153. ```bash
  154. docker run --rm \
  155. -v /path/to/your-ca.crt:/etc/ssl/certs/your-ca.crt:ro \
  156. -e SSL_CERT_FILE=/etc/ssl/certs/your-ca.crt \
  157. -e HA_URL=https://homeassistant.example.internal:8123 \
  158. -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN \
  159. voska/hass-mcp:latest
  160. ```
  161. `SSL_CERT_FILE` always takes precedence over the OS store when set. `verify=False` is intentionally not supported — use `HA_URL=http://...` if you genuinely want unencrypted local LAN traffic.
  162. ## Usage Examples
  163. Here are some examples of prompts you can use with Claude once Hass-MCP is set up:
  164. - "What's the current state of my living room lights?"
  165. - "Turn off all the lights in the kitchen"
  166. - "What's the temperature in the master bedroom?"
  167. - "List everything in the guest room"
  168. - "List all my sensors that contain temperature data"
  169. - "Give me a summary of my climate entities"
  170. - "Create an automation that turns on the lights at sunset"
  171. - "Help me troubleshoot why my bedroom motion sensor automation isn't working"
  172. - "Search for entities related to my living room"
  173. - "Show me the last 50 ERROR lines from the Home Assistant log"
  174. - "What's been failing on the mqtt integration today?"
  175. - "Show me power usage by day for the last month"
  176. - "What happened with the front door sensor last Tuesday?"
  177. ## Available Tools
  178. Hass-MCP provides several tools for interacting with Home Assistant:
  179. - `get_version`: Get the Home Assistant version
  180. - `get_entity`: Get the state of a specific entity with optional field filtering
  181. - `entity_action`: Perform actions on entities (turn on, off, toggle)
  182. - `list_entities`: Get a list of entities with optional domain filtering and search
  183. - `search_entities_tool`: Search for entities matching a query
  184. - `domain_summary_tool`: Get a summary of a domain's entities
  185. - `list_automations`: Get a list of all automations
  186. - `call_service_tool`: Call any Home Assistant service
  187. - `restart_ha`: Restart Home Assistant
  188. - `get_history`: Get the state history of an entity (last N hours)
  189. - `get_history_range`: Get state-change history for an entity over an
  190. explicit date/time range (`start_time` / `end_time`, ISO-8601)
  191. - `get_statistics`: Get long-term aggregated statistics (mean / min / max
  192. per bucket) for an entity over the last N hours — works for data older
  193. than the recorder's short-term retention window
  194. - `get_statistics_range`: Same, but for an explicit date/time range —
  195. useful for monthly / yearly trend queries
  196. - `get_error_log`: Get the Home Assistant error log, with optional
  197. `level` / `integration` / `search_term` / `lines` filters applied
  198. server-side so noisy logs don't blow Claude's context
  199. - `get_entities_by_area`: List entities in a specific area / room
  200. ### Dashboard (Lovelace) Editing
  201. Read and live-edit dashboards over Home Assistant's WebSocket API. Saving
  202. pushes the change to every open browser instantly — no restart.
  203. - `list_dashboards`: List dashboards (the default plus any user dashboards),
  204. each with its `url_path` and `mode` (`storage` / `yaml`)
  205. - `get_dashboard_config`: Get a dashboard's full config
  206. - `set_dashboard_config`: Replace a dashboard's full config (low-level)
  207. - `add_card` / `update_card` / `remove_card` / `move_card`: Edit cards within
  208. a view (the view is selected by index, or by its `path` / `title`)
  209. - `list_view_sections`: List the sections of a "sections"-type view
  210. - `add_view` / `remove_view` / `update_view`: Edit a dashboard's views
  211. - `list_dashboard_backups` / `restore_dashboard`: List and roll back to the
  212. automatic pre-save backups
  213. **Sections views:** Home Assistant's modern view type (`type: sections`) stores
  214. its cards inside sections rather than a single top-level list. For those views,
  215. call `list_view_sections` and pass the `section` argument (index, title, or
  216. heading) to the card tools. Card edits on a sections view without a `section`
  217. are rejected with the list of available sections — rather than silently saving
  218. a card where it would never render.
  219. Every editing tool accepts `dry_run=true` to preview the resulting config and
  220. a change summary without saving.
  221. **Important notes:**
  222. - **Admin token required.** Saving Lovelace config requires the long-lived
  223. token to belong to an admin user.
  224. - **Storage-mode only.** Only UI-managed ("storage") dashboards can be edited.
  225. YAML-mode dashboards are detected and rejected with a clear message — edit
  226. their YAML files directly instead.
  227. - **Whole-config writes.** Home Assistant has no partial-edit API; every change
  228. is a read-modify-write of the entire dashboard. The high-level card/view
  229. tools handle this for you.
  230. - **Automatic backups.** Before each write, the current config is saved to
  231. `HASS_MCP_BACKUP_DIR` (default `~/.hass-mcp/dashboard-backups/`). When running
  232. in **Docker**, mount a volume at this path or backups are lost when the
  233. container is recreated.
  234. ## Prompts for Guided Conversations
  235. Hass-MCP includes several prompts for guided conversations:
  236. - `create_automation`: Guide for creating Home Assistant automations based on trigger type
  237. - `debug_automation`: Troubleshooting help for automations that aren't working
  238. - `troubleshoot_entity`: Diagnose issues with entities
  239. - `routine_optimizer`: Analyze usage patterns and suggest optimized routines based on actual behavior
  240. - `automation_health_check`: Review all automations, find conflicts, redundancies, or improvement opportunities
  241. - `entity_naming_consistency`: Audit entity names and suggest standardization improvements
  242. - `dashboard_layout_generator`: Create optimized dashboards based on user preferences and usage patterns
  243. ## Available Resources
  244. Hass-MCP provides the following resource endpoints:
  245. - `hass://entities/{entity_id}`: Get the state of a specific entity
  246. - `hass://entities/{entity_id}/detailed`: Get detailed information about an entity with all attributes
  247. - `hass://entities`: List all Home Assistant entities grouped by domain
  248. - `hass://entities/domain/{domain}`: Get a list of entities for a specific domain
  249. - `hass://search/{query}/{limit}`: Search for entities matching a query with custom result limit
  250. ## Development
  251. ### Running Tests
  252. ```bash
  253. uv run pytest tests/
  254. ```
  255. ## License
  256. [MIT License](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.