Skip to content
Back to search

homeassistant-mcp

Home Assistant MCP Server - Control your smart home with AI assistants via the Model Context Protocol

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/robbrad--homeassistant-mcp/badge.svg)](/listings/robbrad--homeassistant-mcp)

HTML

<a href="/listings/robbrad--homeassistant-mcp"><img src="/api/listings/robbrad--homeassistant-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.

uvx (recommended)

No install needed. Just configure your MCP client:

{
  "mcpServers": {
    "homeassistant": {
      "command": "uvx",
      "args": ["homeassistant-mcp"],
      "env": {
        "HASS_HOST": "http://homeassistant.local:8123",
        "HASS_TOKEN": "your_long_lived_access_token_here"
      }
    }
  }
}

pip

pip install homeassistant-mcp
homeassistant-mcp

From source

git clone https://github.com/robbrad/homeassistant-mcp.git
cd homeassistant-mcp
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e ".[dev]"
homeassistant-mcp

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 · 256 lines

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

  1. # Home Assistant MCP Server
  2. A Model Context Protocol (MCP) server that lets AI assistants control Home Assistant. Built with Python and [FastMCP](https://github.com/jlowin/fastmcp).
  3. Works with Claude, GPT-4, Cursor, Kiro, and any MCP-compatible client.
  4. ## What it does
  5. - **40 tools** covering lights, climate, covers, locks, media players, vacuums, fans, cameras, alarms, and more
  6. - **BM25 tool search** — LLMs discover tools on demand instead of receiving all 40 schemas upfront
  7. - **MCP Resources** for read-only entity, area, device, and service data
  8. - **MCP Prompts** for guided workflows (automation creation, troubleshooting, energy optimization)
  9. - **Tool annotations** — `readOnlyHint` lets clients skip confirmation prompts for safe operations
  10. - **Smart error log parsing** — deduplicates and summarises HA error logs instead of dumping raw text
  11. - **Context-aware responses** — compact list responses, domain-filtered queries, progress reporting
  12. - **Async throughout** with TTL-based caching to reduce API load
  13. ## Installation
  14. ### uvx (recommended)
  15. No install needed. Just configure your MCP client:
  16. ```json
  17. {
  18. "mcpServers": {
  19. "homeassistant": {
  20. "command": "uvx",
  21. "args": ["homeassistant-mcp"],
  22. "env": {
  23. "HASS_HOST": "http://homeassistant.local:8123",
  24. "HASS_TOKEN": "your_long_lived_access_token_here"
  25. }
  26. }
  27. }
  28. }
  29. ```
  30. ### pip
  31. ```bash
  32. pip install homeassistant-mcp
  33. homeassistant-mcp
  34. ```
  35. ### From source
  36. ```bash
  37. git clone https://github.com/robbrad/homeassistant-mcp.git
  38. cd homeassistant-mcp
  39. python -m venv venv
  40. source venv/bin/activate # Windows: venv\Scripts\activate
  41. pip install -e ".[dev]"
  42. homeassistant-mcp
  43. ```
  44. ## Configuration
  45. The server needs two environment variables:
  46. | Variable | Description |
  47. |----------|-------------|
  48. | `HASS_HOST` | Home Assistant URL, e.g. `http://homeassistant.local:8123` |
  49. | `HASS_TOKEN` | Long-lived access token ([how to create one](https://www.home-assistant.io/docs/authentication/#your-account-profile)) |
  50. Optional:
  51. | Variable | Default | Description |
  52. |----------|---------|-------------|
  53. | `CACHE_TTL_STATES` | `30` | Cache TTL for bulk state queries (seconds) |
  54. | `CACHE_TTL_ENTITY` | `10` | Cache TTL for individual entity queries (seconds) |
  55. | `LOG_LEVEL` | `INFO` | Logging level |
  56. These can be set via environment variables (as shown in the MCP client configs above) or in a `.env` file. See [.env.example](.env.example).
  57. ## MCP Client Setup
  58. ### Claude Desktop
  59. Add to your config file:
  60. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  61. - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  62. ```json
  63. {
  64. "mcpServers": {
  65. "homeassistant": {
  66. "command": "uvx",
  67. "args": ["homeassistant-mcp"],
  68. "env": {
  69. "HASS_HOST": "http://homeassistant.local:8123",
  70. "HASS_TOKEN": "your_token_here"
  71. }
  72. }
  73. }
  74. }
  75. ```
  76. ### Cursor / Kiro / Other MCP Clients
  77. Same config format. Place it in your client's MCP configuration file (e.g. `.cursor/mcp.json`, `.kiro/settings/mcp.json`).
  78. The server uses stdio transport, which is the standard for MCP.
  79. ## How Tool Discovery Works
  80. With 40 tools, the server uses BM25 search to keep the LLM's context lean. Instead of sending all 40 tool schemas upfront, the LLM sees 8 tools:
  81. | Tool | Purpose |
  82. |------|---------|
  83. | `discover_tools` | Returns the full catalog of all 40 tools by category |
  84. | `states_control` | Entity state management (list, get, set, delete) |
  85. | `list_devices` | Device discovery with domain/area/floor filtering |
  86. | `call_service` | Call any HA service directly |
  87. | `template_render` | Render Jinja2 templates in HA context |
  88. | `error_log_get` | Parsed and deduplicated error log summary |
  89. | `search_tools` | BM25 search to find tools by description |
  90. | `call_tool` | Execute a discovered tool by name |
  91. The LLM calls `discover_tools()` to see what's available, then `search_tools(query="lights brightness")` to get the full schema, then calls the tool directly.
  92. ## All Tools
  93. ### Device Control (16 tools)
  94. | Tool | Domain | Capabilities |
  95. |------|--------|-------------|
  96. | `lights_control` | light | Brightness, color temp, RGB |
  97. | `climate_control` | climate | HVAC modes, temperature, fan |
  98. | `switch_control` | switch | On/off, bulk operations |
  99. | `cover_control` | cover | Position, tilt, open/close |
  100. | `lock_control` | lock | Lock/unlock with codes |
  101. | `media_player_control` | media_player | Playback, volume, source |
  102. | `camera_control` | camera | Snapshots, streams, motion detection |
  103. | `vacuum_control` | vacuum | Start, dock, fan speed |
  104. | `fan_control` | fan | Speed, oscillation, direction |
  105. | `alarm_control` | alarm_control_panel | Arm/disarm modes |
  106. | `weather_control` | weather | Conditions, daily/hourly forecasts |
  107. | `water_heater_control` | water_heater | Temperature, modes |
  108. | `humidifier_control` | humidifier | Humidity levels |
  109. | `siren_control` | siren | Activation control |
  110. | `valve_control` | valve | Open/close |
  111. | `lawn_mower_control` | lawn_mower | Start, stop, dock |
  112. ### Automation & Scenes (3 tools)
  113. | Tool | Capabilities |
  114. |------|-------------|
  115. | `automation_control` | List, trigger, enable, disable, reload |
  116. | `scene_control` | List, activate |
  117. | `script_control` | List, execute with variables, reload |
  118. ### Input Helpers (5 tools)
  119. | Tool | Capabilities |
  120. |------|-------------|
  121. | `input_boolean_control` | Toggle on/off |
  122. | `input_number_control` | Set value, increment, decrement |
  123. | `input_select_control` | Select from options |
  124. | `input_text_control` | Set text value |
  125. | `input_datetime_control` | Set date/time |
  126. ### API & State (4 tools)
  127. | Tool | Capabilities |
  128. |------|-------------|
  129. | `api_info` | API status, HA config, loaded components |
  130. | `events_control` | List event types, fire custom events |
  131. | `services_control` | List services by domain, call services |
  132. | `states_control` | List/get/set/delete entity states with filtering |
  133. ### History (3 tools)
  134. | Tool | Capabilities |
  135. |------|-------------|
  136. | `history_query` | State changes by entity + hours (not ISO timestamps) |
  137. | `logbook_query` | Human-readable logbook entries |
  138. | `error_log_get` | Parsed, deduplicated error summary with component counts |
  139. ### Specialized (5 tools)
  140. | Tool | Capabilities |
  141. |------|-------------|
  142. | `calendar_access` | List calendars, get events by date range |
  143. | `camera_proxy_get` | Camera images with optional resize |
  144. | `config_check` | Validate HA configuration |
  145. | `intent_handle` | Process natural language intents |
  146. | `template_render` | Render Jinja2 templates |
  147. ### General (4 tools)
  148. | Tool | Capabilities |
  149. |------|-------------|
  150. | `list_devices` | Filter by any domain, area, or floor |
  151. | `call_service` | Call any HA service with custom data |
  152. | `send_notification` | Send alerts via HA notification services |
  153. | `discover_tools` | Full tool catalog for LLM discovery |
  154. ## MCP Resources
  155. | URI Pattern | Description |
  156. |-------------|-------------|
  157. | `hass://entity/{entity_id}` | Entity state and attributes |
  158. | `hass://area/{area_id}` | Area entities (compact summaries) |
  159. | `hass://device/{device_id}` | Device entities (compact summaries) |
  160. | `hass://services` | All services organized by domain |
  161. | `hass://entity/{entity_id}/history` | Entity history with pagination |
  162. ## Development
  163. ```bash
  164. git clone https://github.com/robbrad/homeassistant-mcp.git
  165. cd homeassistant-mcp
  166. python -m venv venv
  167. source venv/bin/activate
  168. pip install -e ".[dev]"
  169. # Run tests
  170. pytest
  171. # Format and lint
  172. black src/ tests/
  173. ruff check src/ tests/
  174. # Type check
  175. mypy src/
  176. ```
  177. ### Publishing
  178. Commits to `main` auto-publish to PyPI via GitHub Actions + python-semantic-release:
  179. - `fix:` commits → patch bump (3.1.0 → 3.1.1)
  180. - `feat:` commits → minor bump (3.1.0 → 3.2.0)
  181. - `BREAKING CHANGE:` → major bump (3.1.0 → 4.0.0)
  182. ## Architecture
  183. ```
  184. AI Assistant <--> MCP Server (FastMCP/stdio) <--> Home Assistant REST API
  185. |
  186. +-----+-----+
  187. | |
  188. Tools Cache
  189. Layer Layer
  190. ```
  191. - **FastMCP Server** handles MCP protocol over stdio with BM25 tool search
  192. - **Home Assistant Client** is an async httpx client with auth and connection pooling
  193. - **Cache Layer** provides TTL-based caching for states and entities
  194. - **Tools Layer** — 40 tools with annotations, tags, timeouts, and context logging
  195. - **Resources** — 5 read-only data endpoints with compact response envelopes
  196. - **Prompts** — 13 guided workflows for automation, troubleshooting, and optimization
  197. ## License
  198. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

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