[DOCS] Readme is not clear

[Eliav2]

Where is the issue?

Setup Wizard (https://homeassistant-ai.github.io/ha-mcp/setup/)

Link to page (if applicable)

No response

What's wrong or unclear?

just found this porject, cool porject!
i want to install this mcp server on my home assitant OS, not on claude. also its bit unclear what the install script does

How should it be fixed?

No response

Additional context

No response

[github-actions[bot]]

🔍 Analysis

The user's confusion stems from two main points in the documentation:

1. Placement of Home Assistant OS instructions: The "Quick Install" section in the README is heavily focused on "local" installations (running the MCP server on the same machine as the AI client). For users who want to run the server directly on their Home Assistant OS (HAOS) hardware using the official Add-on, the path is less obvious as it's tucked away inside the Setup Wizard.
2. Script Transparency: The quick install scripts for macOS and Windows perform several automated steps (installing uv, configuring Claude Desktop, and setting up a demo environment) which are not explicitly summarized before or during execution. This can be unsettling for users wary of running curl | sh commands.

The user's statement "i want to install this mcp server on my home assitant OS, not on claude" indicates a slight misunderstanding of MCP architecture: the server must still connect to a client (like Claude), but it can be hosted on HAOS. Improving the visibility of the Add-on as a hosting option will clarify this.

🛠️ Suggested Steps

1. Clarify Quick Install scripts: Update the README to explicitly state that the quick install scripts are for a "local" setup with Claude Desktop and a demo environment.
2. Promote HA OS Add-on: Add a dedicated "Home Assistant OS" section to the README's "Quick Install" area to make the Add-on installation method immediately visible.
3. Enhance Script Headers: Add a "What this script does" summary to the beginning of the install-macos.sh and install-windows.ps1 scripts so users see a high-level overview before the automated steps begin.
4. Improve Setup Wizard Discoverability: Consider adding a "Home Assistant OS" quick-start card to the Setup Wizard landing page to cater to users who prioritize the hosting environment over the AI client.

📊 Technical Analysis (for maintainers)

Root Cause

• The README.md "Quick install" section only highlights macOS and Windows scripts, which are designed for a local "try-it-now" experience with Claude Desktop.
• The Home Assistant Add-on is one of the most popular ways to run the server but is currently only discovered by completing the first two steps of the Setup Wizard.
• The install scripts jump straight into "Step 1" without explaining the scope of changes (modifying claude_desktop_config.json, installing uv, etc.).

Affected Code

• README.md - Installation sections.
• scripts/install-macos.sh - Header and user feedback.
• scripts/install-windows.ps1 - Header and user feedback.
• site/src/pages/setup.astro - Hero section and quick start cards.

Proposed Fix

README.md Enhancements

--- a/README.md
+++ b/README.md
@@ -40,6 +40,14 @@
 </p>
 
 ### Quick install (~5 min)
+
+These scripts install `uv` (if needed) and configure **Claude Desktop** to use a **demo environment** so you can try it instantly.
+
+<details>
+<summary><b>🏠 Home Assistant OS (Add-on)</b></summary>
+
+1. Add the repository: `https://github.com/homeassistant-ai/ha-mcp`
+2. Install **"Home Assistant MCP Server"** from the Add-on Store
+3. Start and check the logs for your unique MCP URL
+
+[View Add-on Documentation →](homeassistant-addon/DOCS.md)
+
+</details>

Script Improvements (Example for macOS)

--- a/scripts/install-macos.sh
+++ b/scripts/install-macos.sh
@@ -16,6 +16,13 @@
 printf "${BLUE}   ha-mcp Installer for macOS${NC}\n"
 printf "${BLUE}============================================${NC}\n"
 printf "\n"
+printf "${YELLOW}This script will:${NC}\n"
+printf "  1. Install ${BLUE}uv${NC} (Python tool manager) if not present\n"
+printf "  2. Configure ${BLUE}Claude Desktop${NC} with a demo environment\n"
+printf "  3. Pre-download ${BLUE}ha-mcp${NC} for faster startup\n"
+printf "\n"
+printf "Your existing Claude configuration will be backed up.\n"
+printf "\n"

Related Issues/PRs

• No similar issues found regarding script clarity or HAOS visibility in the README.

---

🤖 Automated analysis by Issue Bot