ha-mcp 4.7.6

Home Assistant MCP Server - Complete control of Home Assistant through MCP

The Unofficial and Awesome Home Assistant MCP Server

A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with Home Assistant.
Using natural language, control smart home devices, query states, execute services and manage your automations.

---

YouTube version →

---

💬 What Can You Do With It?

Just talk to Claude naturally. Here are some real examples:

You Say	What Happens
"Turn off all the lights in the living room"	Finds entities by room using fuzzy search, controls them in bulk
"Is everything healthy? Any devices offline?"	Checks system health, finds unavailable entities, reports issues
"Create an automation that turns on the porch light at sunset"	Creates the automation with proper triggers and actions
"The work-from-home automation doesn't work anymore, check what's going on"	Analyzes execution traces, finds the bug, and auto-fixes it
"Add milk to my shopping list"	Finds your shopping list and adds the item

No YAML editing. No entity ID lookups. Just describe what you want.

---

✨ Features

🔍 Discover, Search and Query

• Fuzzy Entity Search: Comprehensive search with similar words tolerance
• Deep Configuration Search: Search within automation triggers, script sequences, and helper configurations
• AI-Optimized System Overview: Complete system analysis showing entity counts, areas, and device status
• Template Evaluation: Evaluate Home Assistant templates for dynamic data processing and calculations
• Logbook Data Access: Query logbook entries with date filtering and entity-specific searches

🏠 Control

• Universal Service Control: Execute any Home Assistant service with full parameter support
• Real-time State Access: Get detailed entity states with attributes, timestamps, and context information
• Bulk Device Control: Control multiple devices simultaneously with WebSocket verification

🔧 Manage

• Automations and Scripts: Create, modify, delete, enable/disable, and trigger automations
• Helper Entities: Manage input_boolean, input_number, input_select, input_text, input_datetime, input_button
• Groups: Create and manage entity groups for batch control
• Dashboards: Create, update, delete Lovelace dashboards with strategy support
• Areas and Floors: Organize your smart home with areas and floor hierarchy
• Labels: Create and assign labels to entities and areas
• Zones: Define geographic zones for presence detection
• Todo Lists: Manage shopping lists and todo items
• Calendar Events: Create and manage calendar events
• Blueprints: Import and manage automation/script blueprints
• Device Registry: View and manage device information
• Backup and Restore: Create fast local backups and restore with safety mechanisms
• Add-ons: List installed and available add-ons (Supervisor only)

📊 Monitor & Debug

• State History: Query entity state changes over time with flexible time ranges
• Long-term Statistics: Access sensor statistics for energy, climate, and other data
• Camera Snapshots: Capture and retrieve images from camera entities
• Automation Traces: Debug automations by viewing execution traces
• Zigbee/ZHA Devices: Inspect ZHA devices with endpoints and cluster details

---

🚀 Installation

Choose the installation method that best fits your setup:

Method 1: Running Python with UV (Recommended for Claude Desktop)

Best for: Claude Desktop users on any platform

Platform guides: macOS | Windows

Prerequisites:

• UV package manager
  • Windows: winget install astral-sh.uv -e
  • MacOS: brew install uv
• Your Home assistant URL (ex: http://localhost:8123) for HOMEASSISTANT_URL variable
• A Home Assistant long-lived access token (Profile → Security → Long-Lived Access Tokens) for HOMEASSISTANT_TOKEN variable

Client Configuration:

📱 Claude Desktop or any mcp.json format

Config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "Home Assistant": {
      "command": "uvx",
      "args": ["ha-mcp"],
      "env": {
        "HOMEASSISTANT_URL": "http://localhost:8123",
        "HOMEASSISTANT_TOKEN": "your_long_lived_token"
      }
    }
  }
}

Note: replace both HOMEASSISTANT_URL and HOMEASSISTANT_TOKEN with your values.

🆚 VSCode (GitHub Copilot and others)

Prerequisite: Install uvx first

• Windows: winget install astral-sh.uv -e
• macOS: brew install uv

One-click install:

Clicking the button will prompt you for your Home Assistant URL and token.

💻 Claude Code

claude mcp add --transport stdio home-assistant \
  --env HOMEASSISTANT_URL=http://localhost:8123 \
  --env HOMEASSISTANT_TOKEN=your_long_lived_token \
  -- uvx ha-mcp

🌐 Web Clients (Claude.ai, ChatGPT, etc.)

Run the MCP server with uvx (replace the values of the environement variables):

Windows:

set HOMEASSISTANT_URL=http://localhost:8123
set HOMEASSISTANT_TOKEN=your_long_lived_token
set MCP_PORT=8086
set MCP_SECRET_PATH=/__my_secret__
uvx --from ha-mcp ha-mcp-web

Others:

export HOMEASSISTANT_URL=http://localhost:8123
export HOMEASSISTANT_TOKEN=your_long_lived_token
export MCP_PORT=8086
export MCP_SECRET_PATH=/__my_secret__
uvx --from ha-mcp ha-mcp-web

Web client required https and a public URL. You need to use a proxy in front of http://localhost:8086.

Easiest option is to download Cloudflare Tunnel

In another terminal, start Cloudflare Tunnel:

cloudflared tunnel --url http://localhost:8086

Use the public url provided and add your secret path like so https://XYZ.trycloudflare.com/__my_secret__. This url must be used in your Web client MCP configuration and kept secret.

---

Method 2: Home Assistant Add-on

Best for: Users running Home Assistant OS

Advantages:

• ✅ 5 clicks installation
• ✅ Isolated environment
• ✅ Automatic updates
• ✅ Part of your Home Assistant Setup

Installation Steps:

1. Click the button to add the repository to your Home Assistant instance:

   

   Or manually add this repository URL in Supervisor → Add-on Store:

   https://github.com/homeassistant-ai/ha-mcp
   

2. Navigate to the add-on "Home Assistant MCP Server" from the add-on store

3. Click Install, Wait and then Start

4. Follow the configuration instructions for clients in the add-on documentation

---

Method 3: Container

Best for: Home Assistant Container users or when Docker is preferred

Advantages:

• ✅ No installation
• ✅ Isolated environment
• ✅ Automatic updates

Get a long-lived token: Home Assistant → Your Profile → Security → Long-Lived Access Tokens

Client Configuration:

📱 Claude Desktop or any mcp.json format

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add to your mcp.json:

{
  "mcpServers": {
    "home-assistant": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-e", "HOMEASSISTANT_URL=http://homeassistant.local:8123",
        "-e", "HOMEASSISTANT_TOKEN=your_long_lived_token",
        "ghcr.io/homeassistant-ai/ha-mcp:latest"
      ]
    }
  }
}

🌐 Web Clients (Claude.ai, ChatGPT, etc.)

1. Create a docker-compose.yml:

   version: '3.8'
   services:
     ha-mcp:
       image: ghcr.io/homeassistant-ai/ha-mcp:latest
       container_name: ha-mcp
       ports:
         - "8086:8086"
       environment:
         HOMEASSISTANT_URL: http://homeassistant.local:8123
         HOMEASSISTANT_TOKEN: your_long_lived_token
         MCP_SECRET_PATH: /__your_secret_string__
       command: ["fastmcp", "run", "fastmcp-webclient.json"]
       restart: unless-stopped
   
     cloudflared:
       image: cloudflare/cloudflared:latest
       command: tunnel --url http://ha-mcp:8086
       depends_on:
         - ha-mcp
   

2. Start the services:

   docker compose up -d
   

3. Check cloudflared logs for your URL:

   docker compose logs cloudflared
   

4. Use: https://abc-def.trycloudflare.com/__your_secret_string__

💻 Claude Code

claude mcp add-json home-assistant '{
  "command": "docker",
  "args": [
    "run",
    "--rm",
    "-e", "HOMEASSISTANT_URL=http://homeassistant.local:8123",
    "-e", "HOMEASSISTANT_TOKEN=your_long_lived_token",
    "ghcr.io/homeassistant-ai/ha-mcp:latest"
  ]
}'

---

🛠️ Available Tools (82 tools)

🔍 Search & Discovery (4 tools)

Tool	Description
ha_search_entities	Fuzzy entity search with domain filtering
ha_deep_search	Search within automation/script/helper configurations
ha_get_overview	AI-optimized system overview with entity counts
ha_get_state	Get entity state with attributes and context

🎮 Service & Device Control (5 tools)

Tool	Description
ha_call_service	Execute any Home Assistant service
ha_bulk_control	Control multiple devices with WebSocket verification
ha_get_operation_status	Check status of device operations
ha_get_bulk_status	Check status of multiple operations
ha_list_services	List available services by domain

⚙️ Automations (3 tools)

Tool	Description
ha_config_get_automation	Get automation configuration
ha_config_set_automation	Create/update automations
ha_config_remove_automation	Delete automations

📜 Scripts (3 tools)

Tool	Description
ha_config_get_script	Get script configuration
ha_config_set_script	Create/update scripts
ha_config_remove_script	Delete scripts

🔘 Helper Entities (3 tools)

Tool	Description
ha_config_list_helpers	List all helper entities
ha_config_set_helper	Create/update helper entities
ha_config_remove_helper	Delete helper entities

📊 Dashboards (8 tools)

Tool	Description
ha_config_list_dashboards	List all storage-mode dashboards
ha_config_get_dashboard	Get dashboard configuration
ha_config_set_dashboard	Create/update dashboard
ha_config_update_dashboard_metadata	Update dashboard title/icon
ha_config_delete_dashboard	Delete dashboard
ha_get_dashboard_guide	Get dashboard creation guide
ha_get_card_types	List available dashboard card types
ha_get_card_documentation	Get documentation for specific card type

🏠 Areas & Floors (6 tools)

Tool	Description
ha_config_list_areas	List all areas
ha_config_set_area	Create/update area
ha_config_remove_area	Delete area
ha_config_list_floors	List all floors
ha_config_set_floor	Create/update floor
ha_config_remove_floor	Delete floor

🏷️ Labels (5 tools)

Tool	Description
ha_config_list_labels	List all labels
ha_config_get_label	Get label details
ha_config_set_label	Create/update label
ha_config_remove_label	Delete label
ha_assign_label	Assign label to entity/area

📍 Zones (4 tools)

Tool	Description
ha_list_zones	List all zones
ha_create_zone	Create geographic zone
ha_update_zone	Update zone properties
ha_delete_zone	Delete zone

👥 Groups (3 tools)

Tool	Description
ha_config_list_groups	List all entity groups
ha_config_set_group	Create/update entity group
ha_config_remove_group	Delete entity group

✅ Todo Lists (5 tools)

Tool	Description
ha_list_todo_lists	List all todo lists
ha_get_todo_items	Get items from a todo list
ha_add_todo_item	Add item to todo list
ha_update_todo_item	Update todo item
ha_remove_todo_item	Remove todo item

📅 Calendar (3 tools)

Tool	Description
ha_config_get_calendar_events	Get calendar events
ha_config_set_calendar_event	Create/update calendar event
ha_config_remove_calendar_event	Delete calendar event

📋 Blueprints (3 tools)

Tool	Description
ha_list_blueprints	List available blueprints
ha_get_blueprint	Get blueprint details
ha_import_blueprint	Import blueprint from URL

📱 Device Registry (5 tools)

Tool	Description
ha_list_devices	List all devices
ha_get_device	Get device details
ha_update_device	Update device properties
ha_remove_device	Remove device from registry
ha_rename_entity	Rename entity ID

📡 ZHA & Integration Tools (2 tools)

Tool	Description
ha_get_zha_devices	List ZHA (Zigbee) devices with endpoints and clusters
ha_get_entity_integration_source	Get integration source for any entity

🔌 Add-ons (2 tools)

Tool	Description
ha_list_addons	List installed add-ons (Supervisor only)
ha_list_available_addons	List available add-ons from repositories

📷 Camera (1 tool)

Tool	Description
ha_get_camera_image	Capture and retrieve camera snapshot

📈 History & Statistics (2 tools)

Tool	Description
ha_get_history	Query entity state history with time range
ha_get_statistics	Get long-term statistics for sensors

🐞 Automation Traces (1 tool)

Tool	Description
ha_get_automation_traces	Get execution traces for automation debugging

🔄 System & Updates (8 tools)

Tool	Description
ha_check_config	Validate configuration
ha_restart	Restart Home Assistant
ha_reload_core	Reload core configuration
ha_get_system_info	Get system information
ha_get_system_health	Get system health status
ha_list_updates	List available updates
ha_get_release_notes	Get release notes for update
ha_get_system_version	Get Home Assistant version

💾 Backup & Restore (2 tools)

Tool	Description
ha_backup_create	Create fast local backup
ha_backup_restore	Restore from backup

🧰 Utility (4 tools)

Tool	Description
ha_get_logbook	Access historical logbook entries
ha_eval_template	Evaluate Jinja2 templates
ha_get_domain_docs	Get domain documentation
ha_list_integrations	List installed integrations

---

⚙️ Configuration Options

Environment Variables

Variable	Description	Default	Required
HOMEASSISTANT_URL	Home Assistant URL	-	Yes
HOMEASSISTANT_TOKEN	Long-lived access token	-	Yes
BACKUP_HINT	Backup recommendation level	normal	No

Backup Hint Modes:

• strong: Suggests backup before first modification each day/session
• normal: Suggests backup only before irreversible operations (recommended)
• weak: Rarely suggests backups
• auto: Same as normal (future: auto-detection)

---

🤝 Contributing

For development setup, testing instructions, and contribution guidelines, see CONTRIBUTING.md.

For comprehensive testing documentation, see tests/README.md.

---

🛣️ Development Roadmap

Completed ✅

• Core infrastructure and HTTP client
• FastMCP integration with OpenAPI auto-generation
• Smart search tools with fuzzy matching
• Optimized tool documentation to reduce tool call errors
• WebSocket async device control
• Logbook history and operational insights
• Comprehensive test suite
• Home Assistant Add-on support
• Docker images with multi-mode support

For future enhancements and planned features, see the Development Roadmap in our wiki.

---

🔒 Privacy

Ha-mcp runs entirely locally on your machine. We collect no data, send no telemetry, and have no external dependencies beyond your own Home Assistant instance.

• No analytics or tracking
• No cloud services
• Your data stays on your network

For full details, see our Privacy Policy.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Home Assistant: Amazing smart home platform (!)
• FastMCP: Excellent MCP server framework
• Model Context Protocol: Standardized AI-application communication
• Claude Code: AI-powered coding assistant

👥 Contributors

• @julienld — Project maintainer & core contributor.
• @kingbear2 — Windows UV setup guide.