mjrestivo16/mcp-homeassistant

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)

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

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

2. Create virtual environment

   python -m venv venv
   
   # On Windows
   venv\Scripts\activate
   
   # On Linux/Mac
   source venv/bin/activate
   

3. Install dependencies

   pip install -r requirements.txt
   

4. 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

5. 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)

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:

  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