ha-mcp 4.15.1

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.

---

---

🚀 Get Started

Full guide to get you started with Claude Desktop (~10 min)

No paid subscription required. Click on your operating system:

    

Quick install (~5 min)

🍎 macOS

1. Go to claude.ai and sign in (or create a free account)
2. Open Terminal and run:

   curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-macos.sh | sh
   

3. Download Claude Desktop (or restart: Claude menu → Quit)
4. Ask Claude: "Can you see my Home Assistant?"

You're now connected to the demo environment! Connect your own Home Assistant →

🪟 Windows

1. Go to claude.ai and sign in (or create a free account)
2. Open Windows PowerShell (from Start menu) and run:

   irm https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-windows.ps1 | iex
   

3. Download Claude Desktop (or restart: File → Exit)
4. Ask Claude: "Can you see my Home Assistant?"

You're now connected to the demo environment! Connect your own Home Assistant →

Having issues? Check the FAQ & Troubleshooting

---

💬 What Can You Do With It?

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

You Say	What Happens
"Create an automation that turns on the porch light at sunset"	Creates the automation with proper triggers and actions
"Add a weather card to my dashboard"	Updates your Lovelace dashboard with the new card
"The motion sensor automation isn't working, debug it"	Analyzes execution traces, identifies the issue, suggests fixes
"Make my morning routine automation also turn on the coffee maker"	Reads the existing automation, adds the new action, updates it
"Create a script that sets movie mode: dim lights, close blinds, turn on TV"	Creates a reusable script with the sequence of actions

Spend less time configuring, more time enjoying your smart home.

---

✨ Features

Category	Capabilities
🔍 Search	Fuzzy entity search, deep config search, system overview
🏠 Control	Any service, bulk device control, real-time states
🔧 Manage	Automations, scripts, helpers, dashboards, areas, zones, groups, calendars, blueprints
📊 Monitor	History, statistics, camera snapshots, automation traces, ZHA devices
💾 System	Backup/restore, updates, add-ons, device registry

🛠️ Complete Tool List (82 tools)

Category	Tools
Search & Discovery	ha_search_entities, ha_deep_search, ha_get_overview, ha_get_state
Service & Device Control	ha_call_service, ha_bulk_control, ha_get_operation_status, ha_get_bulk_status, ha_list_services
Automations	ha_config_get_automation, ha_config_set_automation, ha_config_remove_automation
Scripts	ha_config_get_script, ha_config_set_script, ha_config_remove_script
Helper Entities	ha_config_list_helpers, ha_config_set_helper, ha_config_remove_helper
Dashboards	ha_config_list_dashboards, ha_config_get_dashboard, ha_config_set_dashboard, ha_config_update_dashboard_metadata, ha_config_delete_dashboard, ha_get_dashboard_guide, ha_get_card_types, ha_get_card_documentation
Areas & Floors	ha_config_list_areas, ha_config_set_area, ha_config_remove_area, ha_config_list_floors, ha_config_set_floor, ha_config_remove_floor
Labels	ha_config_list_labels, ha_config_get_label, ha_config_set_label, ha_config_remove_label, ha_assign_label
Zones	ha_list_zones, ha_create_zone, ha_update_zone, ha_delete_zone
Groups	ha_config_list_groups, ha_config_set_group, ha_config_remove_group
Todo Lists	ha_list_todo_lists, ha_get_todo_items, ha_add_todo_item, ha_update_todo_item, ha_remove_todo_item
Calendar	ha_config_get_calendar_events, ha_config_set_calendar_event, ha_config_remove_calendar_event
Blueprints	ha_list_blueprints, ha_get_blueprint, ha_import_blueprint
Device Registry	ha_list_devices, ha_get_device, ha_update_device, ha_remove_device, ha_rename_entity
ZHA & Integrations	ha_get_zha_devices, ha_get_entity_integration_source
Add-ons	ha_list_addons, ha_list_available_addons
Camera	ha_get_camera_image
History & Statistics	ha_get_history, ha_get_statistics
Automation Traces	ha_get_automation_traces
System & Updates	ha_check_config, ha_restart, ha_reload_core, ha_get_system_info, ha_get_system_health, ha_list_updates, ha_get_release_notes, ha_get_system_version
Backup & Restore	ha_backup_create, ha_backup_restore
Utility	ha_get_logbook, ha_eval_template, ha_get_domain_docs, ha_list_integrations

---

📦 Other Installation Methods

🆚 VSCode (GitHub Copilot)

Prerequisite: Install uv first (winget install astral-sh.uv -e on Windows, brew install uv on macOS)

One-click install:

💻 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@latest

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

Run the MCP server with uvx (replace environment variables):

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@latest ha-mcp-web

Web clients require HTTPS. Use Cloudflare Tunnel:

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

Use the URL: https://XYZ.trycloudflare.com/__my_secret__

🐳 Docker

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

🏠 Home Assistant Add-on

Note: The add-on is just an alternative installation method. You do NOT need it for ha-mcp to work. Most users run ha-mcp directly on their computer.

The add-on is useful if you want to run ha-mcp inside your Home Assistant OS environment.

See add-on documentation for details.

---

🤝 Contributing

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

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

---

🔒 Privacy

Ha-mcp runs locally on your machine. Your smart home data stays on your network.

• Configurable telemetry — optional anonymous usage stats
• No personal data collection — we never collect entity names, configs, or device data
• User-controlled bug reports — only sent with your explicit approval

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.