Home Assistant MCP Server

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

Clone the repository

git clone https://github.com/mjrestivo16/mcp-homeassistant.git
cd mcp-homeassistant

Create virtual environment

python -m venv venv

# On Windows
venv\Scripts\activate

# On Linux/Mac
source venv/bin/activate

Install dependencies
```
pip install -r requirements.txt
```
Configure environment

Create a .env file in the project root:
```
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
Test the server
```
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

{
  "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

# Ask Claude:
"What's the current state of my living room light?"

# Claude uses: get_state("light.living_room")

Control Devices

# 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

# 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

# Ask Claude:
"Show me all my temperature sensors"

# Claude uses: list_entities(domain="sensor")
# Then filters results for temperature entities

View Automation History

# 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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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)

Claude Desktop sends tool calls via stdio
MCP Server processes requests and authenticates with HA token
Home Assistant API executes commands and returns results
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:

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

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
Integrates with Home Assistant
Inspired by the Home Assistant community

Support

Issues: GitHub Issues
Home Assistant Community: Home Assistant Forums
MCP Documentation: MCP Docs

Made with by the Home Assistant community

Home Assistant MCP Server

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

Clone the repository

git clone https://github.com/mjrestivo16/mcp-homeassistant.git
cd mcp-homeassistant

Create virtual environment

python -m venv venv

# On Windows
venv\Scripts\activate

# On Linux/Mac
source venv/bin/activate

Install dependencies
```
pip install -r requirements.txt
```
Configure environment

Create a .env file in the project root:
```
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
Test the server
```
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

{
  "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

# Ask Claude:
"What's the current state of my living room light?"

# Claude uses: get_state("light.living_room")

Control Devices

# 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

# 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

# Ask Claude:
"Show me all my temperature sensors"

# Claude uses: list_entities(domain="sensor")
# Then filters results for temperature entities

View Automation History

# 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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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)

Claude Desktop sends tool calls via stdio
MCP Server processes requests and authenticates with HA token
Home Assistant API executes commands and returns results
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:

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

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
Integrates with Home Assistant
Inspired by the Home Assistant community

Support

Issues: GitHub Issues
Home Assistant Community: Home Assistant Forums
MCP Documentation: MCP Docs

Made with by the Home Assistant community