ha-mcp 3.3.0

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 →

---

✨ 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
• Intelligent Entity Matching: Advanced search across all Home Assistant entities with partial name matching
• 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

🔧 Manage

• Automation and Scripts: Create, modify, delete, enable/disable, and trigger Home Assistant automations
• Helper Entity Management: Create, modify, and delete input_boolean, input_number, input_select, input_text, input_datetime, and input_button entities
• Backup and Restore: Create fast local backups (excludes database) and restore with safety mechanisms

---

🚀 Installation

Choose the installation method that best fits your setup:

Method 1: Home Assistant Add-on (Recommended)

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 2: Container

Best for: Recommended for Home Assistant Container or when Docker is available

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"
  ]
}'

---

Method 3: Running Python with UV

Best for: When Docker is not available

Windows users: Follow the Windows UV setup guide

Prerequisites:

• UV package manager and Git binary
  • Windows: winget install astral-sh.uv Git.Git -e
  • MacOS: brew install git 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": ["--from=git+https://github.com/homeassistant-ai/ha-mcp", "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.

💻 Claude Code

claude mcp add --transport stdio home-assistant \
  --env HOMEASSISTANT_URL=http://localhost:8123 \
  --env HOMEASSISTANT_TOKEN=your_long_lived_token \
  -- uvx --from=git+https://github.com/homeassistant-ai/ha-mcp 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=git+https://github.com/homeassistant-ai/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=git+https://github.com/homeassistant-ai/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.

Development: See CONTRIBUTING.md for testing and contribution guidelines.

---

🛠️ Available Tools

Search & Discovery Tools

Tool	Description	Example
ha_search_entities	Comprehensive entity search with fuzzy matching	ha_search_entities("lumiere salon")
ha_deep_search	Search within automation/script/helper configurations	ha_deep_search("light.turn_on")
ha_get_overview	AI-optimized system overview with entity counts	ha_get_overview()

Core Home Assistant API Tools

Tool	Description	Example
ha_get_state	Get entity state with attributes and context	ha_get_state("light.living_room")
ha_call_service	Execute any Home Assistant service (universal control)	ha_call_service("light", "turn_on", {"entity_id": "light.all"})

Device Control Tools

Tool	Description	Example
ha_bulk_control	Control multiple devices with WebSocket verification	ha_bulk_control([{"entity_id": "light.all", "action": "turn_on"}])
ha_get_operation_status	Check status of device operations	ha_get_operation_status("operation_id")
ha_get_bulk_status	Check status of multiple operations	ha_get_bulk_status(["op1", "op2"])

Configuration Management Tools

Tool	Description	Example
ha_config_set_helper	Create/update helper entities	ha_config_set_helper("input_boolean", "test")
ha_config_remove_helper	Delete helper entities	ha_config_remove_helper("input_boolean", "test")
ha_config_set_script	Create/update scripts	ha_config_set_script("script_id", config)
ha_config_get_script	Get script configuration	ha_config_get_script("script_id")
ha_config_remove_script	Delete scripts	ha_config_remove_script("script_id")
ha_config_set_automation	Create/update automations	ha_config_set_automation(config)
ha_config_get_automation	Get automation configuration	ha_config_get_automation("automation.id")
ha_config_remove_automation	Delete automations	ha_config_remove_automation("automation.id")

History & Insights Tools

Tool	Description	Example
ha_get_logbook	Access historical logbook entries	ha_get_logbook(hours_back=24)

Backup & Restore Tools

Tool	Description	Example
ha_backup_create	Create fast local backup	ha_backup_create("backup_name")
ha_backup_restore	Restore from backup	ha_backup_restore("backup_id")

Template & Documentation Tools

Tool	Description	Example
ha_eval_template	Evaluate Jinja2 templates	ha_eval_template("{{ states('sensor.temp') }}")
ha_get_domain_docs	Get Home Assistant domain documentation	ha_get_domain_docs("light")

---

⚙️ 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.

---

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