homeassistant-mcp-server

# Home Assistant MCP Server > Skill by [ara.so](https://ara.so) — MCP Skills collection ## Overview The Home Assistant MCP Server enables AI assistants (Claude, GPT-4, Cursor, etc.) to control smart home devices through the Model Context Protocol. It provides 40 tools covering lights, climate, covers, locks, media players, vacuums, and more, with BM25 tool search to keep context lean and MCP resources for read-only data access. Built with Python and FastMCP, it uses async operations with TTL-based caching to minimize API load. ## Installation ### uvx (Recommended - No Installation Required) Configure your MCP client with: ```json { "mcpServers": { "homeassistant": { "command": "uvx", "args": ["homeassistant-mcp"], "env": { "HASS_HOST": "http://homeassistant.local:8123", "HASS_TOKEN": "your_long_lived_access_token_here" } } } } ``` ### pip Installation ```bash pip install homeassistant-mcp ``` Run with: ```bash export HASS_HOST="http://homeassistant.local:8123" export HASS_TOKEN="your_token_here" homeassistant-mcp ``` ### From Source ```bash git clone https://github.com/robbrad/homeassistant-mcp.git cd homeassistant-mcp python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -e ".[dev]" homeassistant-mcp ``` ## Configuration ### Required Environment Variables | Variable | Description | Example | |----------|-------------|---------| | `HASS_HOST` | Home Assistant URL | `http://homeassistant.local:8123` | | `HASS_TOKEN` | Long-lived access token | Generate from HA profile page | ### Optional Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `CACHE_TTL_STATES` | `30` | Cache TTL for bulk state queries (seconds) | | `CACHE_TTL_ENTITY` | `10` | Cache TTL for individual entity queries (seconds) | | `LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) | ### Claude Desktop Configuration **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "homeassistant": { "command": "uvx", "args": ["homeassistant-mcp"], "env": { "HASS_HOST": "http://homeassistant.local:8123", "HASS_TOKEN": "eyJ0eXAiOiJKV1QiLCJhbGc..." } } } } ``` ### Cursor Configuration `.cursor/mcp.json`: ```json { "mcpServers": { "homeassistant": { "command": "uvx", "args": ["homeassistant-mcp"], "env": { "HASS_HOST": "${HASS_HOST}", "HASS_TOKEN": "${HASS_TOKEN}" } } } } ``` ## Tool Discovery System The server exposes 8 core tools for tool discovery instead of all 40 upfront: ### Core Discovery Tools ```python # 1. Discover all available tools discover_tools() # Returns: Full catalog of 40 tools organized by category # 2. Search for specific tools by description search_tools(query="lights brightness") # Returns: BM25-ranked tool schemas matching query # 3. Call a discovered tool by name call_tool(tool_name="lights_control", arguments={...}) # Executes the specified tool with given arguments ``` ### Example Tool Discovery Flow ```python # Step 1: Discover what tools are available tools = discover_tools() # Returns categories: Device Control, Automation & Scenes, Input Helpers, etc. # Step 2: Search for specific functionality results = search_tools(query="control lights and brightness") # Returns: lights_control schema with full parameters # Step 3: Use the tool directly lights_control( action="turn_on", entity_id="light.living_room", brightness=80, color_temp=370 ) ``` ## Key Tools by Category ### Device Control Tools (16 total) #### Light Control ```python # Turn on lights with brightness and color lights_control( action="turn_on", entity_id="light.bedroom", brightness=100, # 0-100 rgb_color=[255, 0, 0] # Red ) # Set color temperature lights_control( action="turn_on", entity_id="light.kitchen", color_temp=370 # Warm white (153-500 mireds) ) # Turn off lights_control(action="turn_off", entity_id="light.bedroom") # Bulk operations lights_control( action="turn_on", entity_id="light.all_lights", brightness=50 ) ``` #### Climate Control ```python # Set temperature and mode climate_control( action="set_temperature", entity_id="climate.living_room", temperature=22, # Celsius hvac_mode="heat" # Options: heat, cool, auto, off, heat_cool ) # Set fan mode climate_control( action="set_fan_mode", entity_id="climate.bedroom", fan_mode="auto" # Options: auto, low, medium, high ) # Get current state climate_control(action="get", entity_id="climate.living_room") ``` #### Cover Control ```python # Set position cover_control( action="set_position", entity_id="cover.garage_door", position=50 # 0-100 (0=closed, 100=open) ) # Open/close cover_control(action="open", entity_id="cover.living_room_blinds") cover_control(action="close", entity_id="cover.bedroom_blinds") # Set tilt cover_control( action="set_tilt", entity_id="cover.venetian_blinds", tilt=45 ) ``` #### Lock Control ```python # Lock/unlock lock_control(action="lock", entity_id="lock.front_door") lock_control(action="unlock", entity_id="lock.back_door", code="1234") # Get state lock_control(action="get", entity_id="lock.front_door") ``` #### Media Player Control ```python # Play/pause/stop media_player_control(action="play", entity_id="media_player.living_room_tv") media_player_control(action="pause", entity_id="media_player.spotify") # Volume control media_player_control( action="volume_set", entity_id="media_player.speakers", volume=0.5 # 0.0-1.0 ) # Select source media_player_control( action="select_source", entity_id="media_player.receiver", source="HDMI 1" ) ``` #### Vacuum Control ```python # Start cleaning vacuum_control(action="start", entity_id="vacuum.roborock") # Return to dock vacuum_control(action="dock", entity_id="vacuum.roborock") # Set fan speed vacuum_control( action="set_fan_speed", entity_id="vacuum.roborock", fan_speed="turbo" ) ``` ### State Management ```python # List all entities states_control(action="list") # List entities by domain states_control(action="list", domain="light") # Get specific entity states_control(action="get", entity_id="sensor.temperature") # Set entity state states_control( action="set", entity_id="sensor.custom_sensor", state="active", attributes={"battery": 95} ) # Delete entity state states_control(action="delete", entity_id="sensor.old_sensor") ``` ### Device Discovery ```python # List all devices list_devices() # Filter by domain list_devices(domain="light") # Filter by area list_devices(area="living_room") # Filter by floor list_devices(floor="ground_floor") # Combine filters list_devices(domain="switch", area="bedroom") ``` ### Service Calls ```python # Call any Home Assistant service directly call_service( domain="light", service="turn_on", service_data={ "entity_id": "light.bedroom", "brightness": 80, "rgb_color": [255, 120, 0] } ) # Notify service call_service( domain="notify", service="mobile_app_phone", service_data={ "message": "Motion detected in garage", "title": "Security Alert" } ) # TTS service call_service( domain="tts", service="google_translate_say", service_data={ "entity_id": "media_player.kitchen_speaker", "message": "Dinner is ready" } ) ``` ### Automation Control ```python # List all automations automation_control(action="list") # Trigger automation automation_control(action="trigger", automation_id="automation.morning_routine") # Enable/disable automation_control(action="enable", automation_id="automation.night_mode") automation_control(action="disable", automation_id="automation.away_mode") # Reload automations automation_control(action="reload") ``` ### Scene Control ```python # List scenes scene_control(action="list") # Activate scene scene_control(action="activate", scene_id="scene.movie_time") ``` ### Script Control ```python # List scripts script_control(action="list") # Execute script with variables script_control( action="execute", script_id="script.notification_routine", variables={"message": "Door left open", "priority": "high"} ) # Reload scripts script_control(action="reload") ``` ### Template Rendering ```python # Render Jinja2 templates template_render( template="{{ states('sensor.temperature') | float + 5 }}" ) # Complex template with entity states template_render( template=""" {% set lights = states.light | selectattr('state', 'eq', 'on') | list %} {{ lights | length }} lights are currently on """ ) ``` ### History & Logbook ```python # Get entity history (last N hours) history_query( entity_id="sensor.temperature", hours=24 ) # Get logbook entries logbook_query( entity_id="binary_sensor.front_door", hours=12 ) # Get error log summary (parsed and deduplicated) error_log_get() ``` ### Calendar Access ```python # List all calendars calendar_access(action="list") # Get events for date range calendar_access( action="get_events", calendar_id="calendar.family", start_date="2024-05-01",