Back to search
homeassistant-mcp
SkillGitHub
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
Markdown
[](/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)
- # Home Assistant MCP Server
- A Model Context Protocol (MCP) server that lets AI assistants control Home Assistant. Built with Python and [FastMCP](https://github.com/jlowin/fastmcp).
- Works with Claude, GPT-4, Cursor, Kiro, and any MCP-compatible client.
- ## What it does
- - **40 tools** covering lights, climate, covers, locks, media players, vacuums, fans, cameras, alarms, and more
- - **BM25 tool search** — LLMs discover tools on demand instead of receiving all 40 schemas upfront
- - **MCP Resources** for read-only entity, area, device, and service data
- - **MCP Prompts** for guided workflows (automation creation, troubleshooting, energy optimization)
- - **Tool annotations** — `readOnlyHint` lets clients skip confirmation prompts for safe operations
- - **Smart error log parsing** — deduplicates and summarises HA error logs instead of dumping raw text
- - **Context-aware responses** — compact list responses, domain-filtered queries, progress reporting
- - **Async throughout** with TTL-based caching to reduce API load
- ## Installation
- ### uvx (recommended)
- No install needed. Just configure your MCP client:
- ```json
- {
- "mcpServers": {
- "homeassistant": {
- "command": "uvx",
- "args": ["homeassistant-mcp"],
- "env": {
- "HASS_HOST": "http://homeassistant.local:8123",
- "HASS_TOKEN": "your_long_lived_access_token_here"
- }
- }
- }
- }
- ```
- ### pip
- ```bash
- pip install homeassistant-mcp
- homeassistant-mcp
- ```
- ### From source
- ```bash
- 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
- ```
- ## Configuration
- The server needs two environment variables:
- | Variable | Description |
- |----------|-------------|
- | `HASS_HOST` | Home Assistant URL, e.g. `http://homeassistant.local:8123` |
- | `HASS_TOKEN` | Long-lived access token ([how to create one](https://www.home-assistant.io/docs/authentication/#your-account-profile)) |
- Optional:
- | Variable | Default | Description |
- |----------|---------|-------------|
- | `CACHE_TTL_STATES` | `30` | Cache TTL for bulk state queries (seconds) |
- | `CACHE_TTL_ENTITY` | `10` | Cache TTL for individual entity queries (seconds) |
- | `LOG_LEVEL` | `INFO` | Logging level |
- 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).
- ## MCP Client Setup
- ### Claude Desktop
- Add to your config file:
- - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- ```json
- {
- "mcpServers": {
- "homeassistant": {
- "command": "uvx",
- "args": ["homeassistant-mcp"],
- "env": {
- "HASS_HOST": "http://homeassistant.local:8123",
- "HASS_TOKEN": "your_token_here"
- }
- }
- }
- }
- ```
- ### Cursor / Kiro / Other MCP Clients
- Same config format. Place it in your client's MCP configuration file (e.g. `.cursor/mcp.json`, `.kiro/settings/mcp.json`).
- The server uses stdio transport, which is the standard for MCP.
- ## How Tool Discovery Works
- 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:
- | Tool | Purpose |
- |------|---------|
- | `discover_tools` | Returns the full catalog of all 40 tools by category |
- | `states_control` | Entity state management (list, get, set, delete) |
- | `list_devices` | Device discovery with domain/area/floor filtering |
- | `call_service` | Call any HA service directly |
- | `template_render` | Render Jinja2 templates in HA context |
- | `error_log_get` | Parsed and deduplicated error log summary |
- | `search_tools` | BM25 search to find tools by description |
- | `call_tool` | Execute a discovered tool by name |
- 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.
- ## All Tools
- ### Device Control (16 tools)
- | Tool | Domain | Capabilities |
- |------|--------|-------------|
- | `lights_control` | light | Brightness, color temp, RGB |
- | `climate_control` | climate | HVAC modes, temperature, fan |
- | `switch_control` | switch | On/off, bulk operations |
- | `cover_control` | cover | Position, tilt, open/close |
- | `lock_control` | lock | Lock/unlock with codes |
- | `media_player_control` | media_player | Playback, volume, source |
- | `camera_control` | camera | Snapshots, streams, motion detection |
- | `vacuum_control` | vacuum | Start, dock, fan speed |
- | `fan_control` | fan | Speed, oscillation, direction |
- | `alarm_control` | alarm_control_panel | Arm/disarm modes |
- | `weather_control` | weather | Conditions, daily/hourly forecasts |
- | `water_heater_control` | water_heater | Temperature, modes |
- | `humidifier_control` | humidifier | Humidity levels |
- | `siren_control` | siren | Activation control |
- | `valve_control` | valve | Open/close |
- | `lawn_mower_control` | lawn_mower | Start, stop, dock |
- ### Automation & Scenes (3 tools)
- | Tool | Capabilities |
- |------|-------------|
- | `automation_control` | List, trigger, enable, disable, reload |
- | `scene_control` | List, activate |
- | `script_control` | List, execute with variables, reload |
- ### Input Helpers (5 tools)
- | Tool | Capabilities |
- |------|-------------|
- | `input_boolean_control` | Toggle on/off |
- | `input_number_control` | Set value, increment, decrement |
- | `input_select_control` | Select from options |
- | `input_text_control` | Set text value |
- | `input_datetime_control` | Set date/time |
- ### API & State (4 tools)
- | Tool | Capabilities |
- |------|-------------|
- | `api_info` | API status, HA config, loaded components |
- | `events_control` | List event types, fire custom events |
- | `services_control` | List services by domain, call services |
- | `states_control` | List/get/set/delete entity states with filtering |
- ### History (3 tools)
- | Tool | Capabilities |
- |------|-------------|
- | `history_query` | State changes by entity + hours (not ISO timestamps) |
- | `logbook_query` | Human-readable logbook entries |
- | `error_log_get` | Parsed, deduplicated error summary with component counts |
- ### Specialized (5 tools)
- | Tool | Capabilities |
- |------|-------------|
- | `calendar_access` | List calendars, get events by date range |
- | `camera_proxy_get` | Camera images with optional resize |
- | `config_check` | Validate HA configuration |
- | `intent_handle` | Process natural language intents |
- | `template_render` | Render Jinja2 templates |
- ### General (4 tools)
- | Tool | Capabilities |
- |------|-------------|
- | `list_devices` | Filter by any domain, area, or floor |
- | `call_service` | Call any HA service with custom data |
- | `send_notification` | Send alerts via HA notification services |
- | `discover_tools` | Full tool catalog for LLM discovery |
- ## MCP Resources
- | URI Pattern | Description |
- |-------------|-------------|
- | `hass://entity/{entity_id}` | Entity state and attributes |
- | `hass://area/{area_id}` | Area entities (compact summaries) |
- | `hass://device/{device_id}` | Device entities (compact summaries) |
- | `hass://services` | All services organized by domain |
- | `hass://entity/{entity_id}/history` | Entity history with pagination |
- ## Development
- ```bash
- git clone https://github.com/robbrad/homeassistant-mcp.git
- cd homeassistant-mcp
- python -m venv venv
- source venv/bin/activate
- pip install -e ".[dev]"
- # Run tests
- pytest
- # Format and lint
- black src/ tests/
- ruff check src/ tests/
- # Type check
- mypy src/
- ```
- ### Publishing
- Commits to `main` auto-publish to PyPI via GitHub Actions + python-semantic-release:
- - `fix:` commits → patch bump (3.1.0 → 3.1.1)
- - `feat:` commits → minor bump (3.1.0 → 3.2.0)
- - `BREAKING CHANGE:` → major bump (3.1.0 → 4.0.0)
- ## Architecture
- ```
- AI Assistant <--> MCP Server (FastMCP/stdio) <--> Home Assistant REST API
- |
- +-----+-----+
- | |
- Tools Cache
- Layer Layer
- ```
- - **FastMCP Server** handles MCP protocol over stdio with BM25 tool search
- - **Home Assistant Client** is an async httpx client with auth and connection pooling
- - **Cache Layer** provides TTL-based caching for states and entities
- - **Tools Layer** — 40 tools with annotations, tags, timeouts, and context logging
- - **Resources** — 5 read-only data endpoints with compact response envelopes
- - **Prompts** — 13 guided workflows for automation, troubleshooting, and optimization
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.