# Home Assistant MCP Server
[](https://www.python.org/downloads/)
[](https://pypi.org/project/mcp/)
[](LICENSE)
A Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with Home Assistant. Control smart home devices, manage automations, query entity states, and more through a standardized AI-to-home-automation interface.
## Features
### Core Capabilities
- **Entity State Management**: Query current state and attributes of any Home Assistant entity
- **Entity Discovery**: List and filter entities by domain (lights, sensors, switches, etc.)
- **Service Calls**: Execute any Home Assistant service to control devices
- **Historical Data**: Retrieve entity state history over configurable time periods
- **Automation Triggers**: Manually trigger automations
### Automation Management
- **Create Automations**: Build new automations from YAML configuration
- **Update Automations**: Modify existing automation configurations
- **Delete Automations**: Remove automations programmatically
- **View Configurations**: Retrieve full YAML config for any automation
- **List All Automations**: Get complete inventory of automation configs
- **Reload Automations**: Refresh automation configuration after changes
- **Enable/Disable**: Toggle automations on or off
## Available Tools (13)
| Tool | Description |
|------|-------------|
| `get_state` | Get current state and attributes of any entity |
| `list_entities` | List entities with optional domain filtering |
| `call_service` | Execute any Home Assistant service |
| `trigger_automation` | Manually trigger an automation |
| `get_history` | Retrieve historical state changes |
| `create_automation` | Create new automation from config |
| `update_automation` | Modify existing automation |
| `delete_automation` | Remove an automation |
| `get_automation_config` | View full automation YAML |
| `list_automation_configs` | List all automation configurations |
| `reload_automations` | Reload automation configuration |
| `enable_automation` | Enable a disabled automation |
| `disable_automation` | Disable an active automation |
## Installation
### Prerequisites
- Python 3.10 or higher
- Home Assistant instance (local or remote)
- Home Assistant Long-Lived Access Token
### Setup Steps
1. **Clone the repository**
```bash
git clone https://github.com/mjrestivo16/mcp-homeassistant.git
cd mcp-homeassistant
```
2. **Create virtual environment**
```bash
python -m venv venv
# On Windows
venv\Scripts\activate
# On Linux/Mac
source venv/bin/activate
```
3. **Install dependencies**
```bash
pip install -r requirements.txt
```
4. **Configure environment**
Create a `.env` file in the project root:
```env
HA_URL=http://192.168.1.100:8123
HA_TOKEN=your_long_lived_access_token_here
```
To generate a Long-Lived Access Token:
1. Log into Home Assistant
2. Click your profile (bottom left)
3. Scroll to "Long-Lived Access Tokens"
4. Click "Create Token"
5. Give it a name (e.g., "MCP Server")
6. Copy the token to your `.env` file
5. **Test the server**
```bash
python server.py
```
## Configuration for Claude Desktop
Add this configuration to your Claude Desktop config file:
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"homeassistant": {
"type": "stdio",
"command": "python",
"args": ["C:/path/to/mcp-homeassistant/server.py"],
"env": {
"HA_URL": "http://192.168.1.100:8123",
"HA_TOKEN": "your_long_lived_access_token_here"
}
}
}
}
```
**Note**: Use absolute paths in the configuration. Restart Claude Desktop after adding the configuration.
## Usage Examples
### Query Entity State
```python
# Ask Claude:
"What's the current state of my living room light?"
# Claude uses: get_state("light.living_room")
```
### Control Devices
```python
# Ask Claude:
"Turn on the bedroom light at 50% brightness"
# Claude uses: call_service(
# domain="light",
# service="turn_on",
# entity_id="light.bedroom",
# data={"brightness_pct": 50}
# )
```
### Create Automation
```python
# Ask Claude:
"Create an automation that turns on the porch light at sunset"
# Claude uses: create_automation({
# "id": "porch_light_sunset",
# "alias": "Porch Light at Sunset",
# "trigger": {
# "platform": "sun",
# "event": "sunset"
# },
# "action": {
# "service": "light.turn_on",
# "target": {"entity_id": "light.porch"}
# }
# })
```
### List Entities by Domain
```python
# Ask Claude:
"Show me all my temperature sensors"
# Claude uses: list_entities(domain="sensor")
# Then filters results for temperature entities
```
### View Automation History
```python
# Ask Claude:
"Show me the history of my thermostat for the last 12 hours"
# Claude uses: get_history(
# entity_id="climate.living_room",
# hours=12
# )
```
## API Reference
### get_state
Get the current state and attributes of any Home Assistant entity.
**Parameters:**
- `entity_id` (string, required): Entity ID (e.g., `light.office`, `sensor.temperature`)
**Returns:** Formatted text with entity state and all attributes
**Example:**
```json
{
"entity_id": "light.living_room"
}
```
---
### list_entities
List all entities, optionally filtered by domain.
**Parameters:**
- `domain` (string, optional): Domain filter (e.g., `light`, `sensor`, `automation`)
**Returns:** List of entities with their current states (limited to first 50)
**Example:**
```json
{
"domain": "light"
}
```
---
### call_service
Call any Home Assistant service to control devices.
**Parameters:**
- `domain` (string, required): Service domain (e.g., `light`, `climate`, `switch`)
- `service` (string, required): Service name (e.g., `turn_on`, `turn_off`, `set_temperature`)
- `entity_id` (string, required): Target entity ID
- `data` (object, optional): Additional service data (e.g., brightness, temperature)
**Returns:** Success confirmation message
**Example:**
```json
{
"domain": "light",
"service": "turn_on",
"entity_id": "light.bedroom",
"data": {
"brightness_pct": 75,
"color_temp": 370
}
}
```
---
### trigger_automation
Manually trigger a Home Assistant automation.
**Parameters:**
- `entity_id` (string, required): Automation entity ID (e.g., `automation.morning_routine`)
**Returns:** Success confirmation message
**Example:**
```json
{
"entity_id": "automation.morning_routine"
}
```
---
### get_history
Get historical state changes for an entity.
**Parameters:**
- `entity_id` (string, required): Entity ID to get history for
- `hours` (number, optional): Number of hours of history (default: 24)
**Returns:** Last 10 state changes within the time period
**Example:**
```json
{
"entity_id": "sensor.outdoor_temperature",
"hours": 12
}
```
---
### create_automation
Create a new Home Assistant automation from YAML configuration.
**Parameters:**
- `automation_config` (object, required): Complete automation configuration including:
- `id` (string, required): Unique automation ID
- `alias` (string, required): Human-readable name
- `trigger` (object/array, required): Trigger configuration
- `action` (object/array, required): Action configuration
- `condition` (object/array, optional): Condition configuration
- `mode` (string, optional): Automation mode (single, restart, queued, parallel)
**Returns:** Success confirmation with automation ID
**Example:**
```json
{
"automation_config": {
"id": "motion_light_kitchen",
"alias": "Kitchen Motion Light",
"trigger": {
"platform": "state",
"entity_id": "binary_sensor.kitchen_motion",
"to": "on"
},
"action": {
"service": "light.turn_on",
"target": {"entity_id": "light.kitchen"}
}
}
}
```
---
### update_automation
Update an existing Home Assistant automation.
**Parameters:**
- `automation_id` (string, required): The automation ID (not entity_id)
- `automation_config` (object, required): Updated automation configuration
**Returns:** Success confirmation with automation ID
**Example:**
```json
{
"automation_id": "motion_light_kitchen",
"automation_config": {
"id": "motion_light_kitchen",
"alias": "Kitchen Motion Light (Updated)",
"trigger": {
"platform": "state",
"entity_id": "binary_sensor.kitchen_motion",
"to": "on"
},
"action": [
{
"service": "light.turn_on",
"target": {"entity_id": "light.kitchen"},
"data": {"brightness_pct": 100}
}
]
}
}
```
---
### delete_automation
Delete a Home Assistant automation.
**Parameters:**
- `automation_id` (string, required): The automation ID to delete (not entity_id)
**Returns:** Success confirmation
**Example:**
```json
{
"automation_id": "old_automation_id"
}
```
---
### get_automation_config
Get the full YAML configuration of an automation.
**Parameters:**
- `automation_id` (string, required): The automation ID (not entity_id)
**Returns:** Full automation configuration as JSON
**Example:**
```json
{
"automation_id": "motion_light_kitchen"
}
```
---
### list_automation_configs
List all automation configurations (full YAML configs, not just states).
**Parameters:** None
**Returns:** List of all automations with their IDs and aliases
---
### reload_automations
Reload all automations after making changes.
**Parameters:** None
**Returns:** Success confirmation
---
### enable_automation
Enable a disabled automation.
**Parameters:**
- `entity_id` (string, required): Automation entity ID (e.g., `automation.morning_routine`)
**Returns:** Success confirmation
**Example:**
```json
{
"entity_id": "automation.morning_routine"
}
```
---
### disable_automation
Disable an active automation.
**Parameters:**
- `entity_id` (string, required): Automation entity ID (e.g., `automation.morning_routine`)
**Returns:** Success confirmation
**Example:**
```json
{
"entity_id": "automation.morning_routine"
}
```
## Architecture
### Technology Stack
- **Python 3.10+**: Core runtime
- **MCP SDK 1.21.2**: Model Context Protocol implementation
- **httpx**: Async HTTP client for Home Assistant API
- **python-dotenv**: Environment configuration management
### Communication Flow
```
Claude Desktop → MCP Server (stdio) → Home Assistant API (REST)
```
1. Claude Desktop sends tool calls via stdio
2. MCP Server processes requests and authenticates with HA token
3. Home Assistant API executes commands and returns results
4. MCP Server formats responses for Claude
### Error Handling
- HTTP status errors from Home Assistant API
- Request timeouts (30 second default)
- Authentication failures
- Malformed automation configurations
## Troubleshooting
### Server won't start
- Verify Python version: `python --version` (must be 3.10+)
- Check virtual environment is activated
- Ensure all dependencies installed: `pip install -r requirements.txt`
### Authentication errors
- Verify Home Assistant URL is correct and accessible
- Test token with curl:
```bash
curl -H "Authorization: Bearer YOUR_TOKEN" http://YOUR_HA_URL/api/
```
- Regenerate token if expired
### Tools not appearing in Claude
- Restart Claude Desktop after config changes
- Check Claude Desktop logs (Help → View Logs)
- Verify absolute paths in configuration
- Ensure no JSON syntax errors in config file
### Automation changes not taking effect
- Use `reload_automations` tool after creating/updating automations
- Check Home Assistant logs for YAML syntax errors
- Verify automation IDs are unique
## Security Considerations
- **Never commit `.env` files** to version control
- Store Home Assistant tokens securely
- Use network isolation for production deployments
- Consider enabling Home Assistant authentication logs
- Regularly rotate access tokens
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
### Development Setup
```bash
git clone https://github.com/mjrestivo16/mcp-homeassistant.git
cd mcp-homeassistant
python -m venv venv
source venv/bin/activate # or venv\Scripts\activate on Windows
pip install -r requirements.txt
```
## License
MIT License - see LICENSE file for details
## Acknowledgments
- Built on the [Model Context Protocol](https://modelcontextprotocol.io/)
- Integrates with [Home Assistant](https://www.home-assistant.io/)
- Inspired by the Home Assistant community
## Support
- **Issues**: [GitHub Issues](https://github.com/mjrestivo16/mcp-homeassistant/issues)
- **Home Assistant Community**: [Home Assistant Forums](https://community.home-assistant.io/)
- **MCP Documentation**: [MCP Docs](https://modelcontextprotocol.io/docs)
---
**Made with by the Home Assistant community**
