Skip to main content
Glama
mjrestivo16

Home Assistant MCP Server

by mjrestivo16
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

Home Assistant MCP Server

Python 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

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

Support

Made with by the Home Assistant community

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mjrestivo16/mcp-homeassistant'

If you have feedback or need assistance with the MCP directory API, please join our Discord server