DOCSEARCHbyAlgolia
Submit Docs

Home Assistant MCP Server

repository·master·Indexed 26 days ago

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

A Model Context Protocol (MCP) server that bridges AI assistants and Home Assistant. It enables LLMs to control smart home devices, manage automations, and query device states using natural language. Features include over 70 tools for device and automation control, fuzzy search for entities, and support for multiple installation methods including HACS, Home Assistant Add-ons, Docker, and PyPI.

Tokens
42.5K
Snippets
48
Records
220
Agent score
88%

What's inside ha-mcp

  1. Overview of Home Assistant MCP Server features

    master

    The Home Assistant MCP Server Add-on provides the following capabilities for AI-driven home automation:

    • Device & Automation Control: Access to 70+ tools for managing entities, automations, and devices.
    • Zero Configuration: Automatically discovers your Home Assistant connection.
    • Security: Uses auto-generated secret paths to ensure secure communication.
    • Fuzzy Search: Enables finding entities even when queries contain typos.
    • Management: Includes backup and restore capabilities for safe configuration management.

  2. Overview of the Home Assistant MCP Server

    master

    The Home Assistant MCP Server is a Model Context Protocol (MCP) server that allows AI assistants to interact with your Home Assistant instance. It enables AI to control smart home devices, query device states, execute services, and manage automations using natural language.

    Note: As of version 7.3.0, the ha_config_set_yaml tool has been moved to beta and can be found in the beta documentation.

  3. Understand the relationship between In-Process Server and File & YAML Tools

    master

    The in-process server entry and the HA-MCP File & YAML Tools entry are two distinct configuration entries of the same custom component (ha_mcp_tools).

    • They are independent: The server runs on its own without the File & YAML entry.
    • File & YAML Tools: This entry should only be added if you want to enable the opt-in file and YAML editing tools (which are off by default). These tools use privileged services registered by the File & YAML entry.
    • Adding or removing the HA-MCP File & YAML Tools entry does not affect how the in-process server operates.

  4. Understand the privacy scope of ha-mcp

    master
    The ha-mcp privacy policy applies exclusively to the Home Assistant MCP Server software. It does not cover the MCP host or client application (e.g., Claude Desktop, IDEs, etc.) used to run the server. Data accessed from your Home Assistant instance is processed by your MCP client and is subject to that client's specific privacy policy. ha-mcp itself does not collect, store, or transmit your Home Assistant data.

  5. Configure the MCP server URL

    master

    By default, the addon uses auto-detection for the MCP server URL. It searches for the ha_mcp (stable) or ha_mcp_dev (dev) addon, retrieves its container IP via the Supervisor API, and discovers the secret path.

    If auto-detection fails (e.g., due to non-standard ports or custom networking), manually set mcp_server_url to the full URL.

    http://192.168.1.100:9583/private_zctpwlX7ZkIAr7oqdfLPxw

  6. Install the ha-mcp dev channel via pip

    master

    You can install the development version of the package using pip. Note that you may need sudo or administrator privileges depending on your system configuration.

    To install the dev version for your user:

    pip install --user ha-mcp-dev

    To run the installed package:

    ha-mcp-dev

    To switch back to stable, uninstall the dev package and install the stable one:

    pip uninstall ha-mcp-dev -y
pip install --user ha-mcp
    pip install --user ha-mcp-dev
ha-mcp-dev

  7. Install the Home Assistant MCP Server Add-on

    master

    To enable AI assistant integration with Home Assistant via Model Context Protocol (MCP), install the add-on using these steps:

    1. Add the repository to your Home Assistant instance via Supervisor → Add-on Store using this URL: https://github.com/homeassistant-ai/ha-mcp
    2. Find the add-on named "Home Assistant MCP Server" in the store.
    3. Install, Wait, and Start the add-on.
    4. Retrieve your unique MCP Server URL from the add-on logs. It will look like: http://<IP_ADDRESS>:9583/private_<SECRET_TOKEN>

    Note: This add-on automatically discovers your Home Assistant connection and uses a secure, auto-generated secret path for authentication.

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

  8. Enable OAuth 2.1 (Beta) using Home Assistant (`ha_auth`)

    master

    The ha_auth mode is the recommended way to add a security layer. It uses Home Assistant itself as the authorization server.

    1. In the addon Configuration tab, toggle Show unused optional configuration options.
    2. Set Enable OAuth (Beta) to on.
    3. Leave OAuth Mode unset (or set to ha_auth).
    4. Save and restart the addon.
    5. In your MCP client (e.g., Claude.ai), add the connector using the webhook URL and leave the OAuth Client ID and Client Secret fields blank.
    6. Follow the browser prompts to sign in with your Home Assistant account and approve access.

    To revoke access, remove the session/refresh token in Home Assistant under Settings → your user → Security.

  9. Configure Claude Desktop with Home Assistant MCP

    master

    Claude Desktop requires mcp-proxy to communicate with the Home Assistant add-on's HTTP endpoint.

    1. Install uv

    First, ensure uv is installed on your machine:

    macOS / Linux:

    curl -LsSf https://astral.sh/uv/install.sh | sh

    Windows (PowerShell):

    winget install --id=astral-sh.uv -e

    2. Update Claude Desktop Configuration

    Add the following to your claude_desktop_config.json file.

    File Locations:

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

    Configuration Snippet:

    {
  "mcpServers": {
    "home-assistant": {
      "command": "uvx",
      "args": ["--with", "mcp<2.0.0", "mcp-proxy", "--transport", "streamablehttp", "http://192.168.1.100:9583/private_zctpwlX7ZkIAr7oqdfLPxw"]
    }
  }
}

    Important:

    • Replace the URL in args with the unique URL found in your add-on logs.
    • The flag --with "mcp<2.0.0" is required to prevent ImportError issues with mcp-proxy.
    • Restart Claude Desktop after saving the file.
    {
  "mcpServers": {
    "home-assistant": {
      "command": "uvx",
      "args": ["--with", "mcp<2.0.0", "mcp-proxy", "--transport", "streamablehttp", "http://192.168.1.100:9583/private_zctpwlX7ZkIAr7oqdfLPxw"]
    }
  }
}

  10. Enable and use filesystem tools

    master

    Direct filesystem access is provided via ha_list_files, ha_read_file, ha_write_file, and ha_delete_file.

    Requirements:

    1. Install the ha_mcp_tools custom component via HACS (repository homeassistant-ai/ha-mcp-integration).
    2. Set the environment variable HAMCP_ENABLE_FILESYSTEM_TOOLS=true.

    Access Scopes:

    • Default writable directories: www/, themes/, custom_templates/, and dashboards/.
    • Default readable directories: Config YAML files, logs, and custom_components/.
    • Extended access: You can opt-in to additional read/write access for directories like /share, /media, /ssl, or /backup via the Web Settings UI.

    Warning: ha_delete_file and ha_write_file (with overwrite=True) are irreversible and have no automatic backup or recycle bin.

  11. Set up ha-mcp OAuth Server

    master

    Use OAuth mode if you require multi-user support where each user authenticates with their own Home Assistant Long-Lived Access Token via a consent form.

    Prerequisites:

    1. Expose with HTTPS: The server must be accessible via a public HTTPS URL. For testing, you can use a Cloudflare tunnel:
      cloudflared tunnel --url http://localhost:8086
    2. Environment Variables: You must provide HOMEASSISTANT_URL and MCP_BASE_URL.

    Startup Commands:

    Docker:

    docker run -d --name ha-mcp-oauth \
  -p 8086:8086 \
  -e HOMEASSISTANT_URL=http://homeassistant.local:8123 \
  -e MCP_BASE_URL=https://your-tunnel.trycloudflare.com \
  ghcr.io/homeassistant-ai/ha-mcp:latest \
  ha-mcp-oauth

    uvx:

    export HOMEASSISTANT_URL=http://homeassistant.local:8123
export MCP_BASE_URL=https://your-tunnel.trycloudflare.com
uvx --from=ha-mcp@latest ha-mcp-oauth

  12. Configure Dashboard Screenshots with Puppet

    master

    Screenshotting is handled by an external engine: Puppet.

    Setup Instructions:

    1. HA OS / Supervised:

    • Add the Puppet repository: https://github.com/balloob/home-assistant-addons.
    • Install the Puppet add-on.
    • Set the access_token option to a Home Assistant long-lived access token.
    • Start the add-on.

    2. Docker / Container:

    • Run Puppet's image as a sidecar.
    • Set the access_token in the container.
    • Set the environment variable HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL=http://<engine-host>:10000 in your ha-mcp configuration.

    Usage Details:

    • Authentication: A long-lived access token is mandatory. Use a dedicated, low-privilege user if possible.
    • Full Page Captures: Use height="auto" or full_page=true to capture content below the fold (capped at 4000px by Puppet).
    • View Addressing: Use dashboard_url_path and the view's path for stable addressing.
    • Security Warning: Puppet's HTTP listener (port 10000) has no inbound authentication. Do not expose this port to the internet.