Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/voska/hass-mcp


https://github.com/voska/hass-mcp

Last synced: 8 months ago
JSON representation

Awesome Lists containing this project

README 

          
# Hass-MCP



A Model Context Protocol (MCP) server for Home Assistant integration with Claude and other LLMs.



## Overview



Hass-MCP enables AI assistants like Claude to interact directly with your Home Assistant instance, allowing them to:



- Query the state of devices and sensors

- Control lights, switches, and other entities

- Get summaries of your smart home

- Troubleshoot automations and entities

- Search for specific entities

- Create guided conversations for common tasks



## Screenshots



Screenshot 2025-03-16 at 15 48 01

Screenshot 2025-03-16 at 15 50 59

Screenshot 2025-03-16 at 15 49 26



## Features



- **Entity Management**: Get states, control devices, and search for entities

- **Domain Summaries**: Get high-level information about entity types

- **Automation Support**: List and control automations

- **Guided Conversations**: Use prompts for common tasks like creating automations

- **Smart Search**: Find entities by name, type, or state

- **Token Efficiency**: Lean JSON responses to minimize token usage



## Installation



### Prerequisites



- Home Assistant instance with Long-Lived Access Token

- One of the following:

  - Docker (recommended)

  - Python 3.13+ and [uv](https://github.com/astral-sh/uv)



## Setting Up With Claude Desktop



### Docker Installation (Recommended)



1. Pull the Docker image:



   ```bash

   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:



   ```json

   {

     "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`.



## Other MCP Clients



### Cursor



1. Go to Cursor Settings > MCP > Add New MCP Server

2. Fill in the form:

   - Name: `Hass-MCP`

   - Type: `command`

   - Command:

     ```

     docker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN voska/hass-mcp

     ```

   - Replace `YOUR_LONG_LIVED_TOKEN` with your actual Home Assistant token

   - Update the HA_URL to match your Home Assistant instance address

3. Click "Add" to save



### Claude Code (CLI)



To use with Claude Code CLI, you can add the MCP server directly using the `mcp add` command:



**Using Docker (recommended):**



```bash

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

```



Replace `YOUR_LONG_LIVED_TOKEN` with your actual Home Assistant token and update the HA_URL to match your Home Assistant instance address.



## Usage Examples



Here are some examples of prompts you can use with Claude once Hass-MCP is set up:



- "What's the current state of my living room lights?"

- "Turn off all the lights in the kitchen"

- "List all my sensors that contain temperature data"

- "Give me a summary of my climate entities"

- "Create an automation that turns on the lights at sunset"

- "Help me troubleshoot why my bedroom motion sensor automation isn't working"

- "Search for entities related to my living room"



## Available Tools



Hass-MCP provides several tools for interacting with Home Assistant:



- `get_version`: Get the Home Assistant version

- `get_entity`: Get the state of a specific entity with optional field filtering

- `entity_action`: Perform actions on entities (turn on, off, toggle)

- `list_entities`: Get a list of entities with optional domain filtering and search

- `search_entities_tool`: Search for entities matching a query

- `domain_summary_tool`: Get a summary of a domain's entities

- `list_automations`: Get a list of all automations

- `call_service_tool`: Call any Home Assistant service

- `restart_ha`: Restart Home Assistant

- `get_history`: Get the state history of an entity

- `get_error_log`: Get the Home Assistant error log



## Prompts for Guided Conversations



Hass-MCP includes several prompts for guided conversations:



- `create_automation`: Guide for creating Home Assistant automations based on trigger type

- `debug_automation`: Troubleshooting help for automations that aren't working

- `troubleshoot_entity`: Diagnose issues with entities

- `routine_optimizer`: Analyze usage patterns and suggest optimized routines based on actual behavior

- `automation_health_check`: Review all automations, find conflicts, redundancies, or improvement opportunities

- `entity_naming_consistency`: Audit entity names and suggest standardization improvements

- `dashboard_layout_generator`: Create optimized dashboards based on user preferences and usage patterns



## Available Resources



Hass-MCP provides the following resource endpoints:



- `hass://entities/{entity_id}`: Get the state of a specific entity

- `hass://entities/{entity_id}/detailed`: Get detailed information about an entity with all attributes

- `hass://entities`: List all Home Assistant entities grouped by domain

- `hass://entities/domain/{domain}`: Get a list of entities for a specific domain

- `hass://search/{query}/{limit}`: Search for entities matching a query with custom result limit



## Development



### Running Tests



```bash

uv run pytest tests/

```



## License



[MIT License](LICENSE)