[BUG] OAuth still requires HOMEASSISTANT_TOKEN

[calvinbui]

💬 What Went Wrong?

Running the server in OAuth mode still requires the HOMEASSISTANT_TOKEN variable, contrary to the documentation which mentions:

HOMEASSISTANT_TOKEN is NOT required in OAuth mode. Each user provides their own Long-Lived Access Token via the consent form.

📋 AI-Generated Content / Logs / Config

2026-04-06 11:00:48 ha_mcp.__main__ INFO: OAuth mode logging configured at INFO level
2026-04-06 11:00:48 ha_mcp.auth.provider INFO: HomeAssistantOAuthProvider initialized with base_url=https://home-assistant-mcp.example.com
2026-04-06 11:00:48 ha_mcp.__main__ ERROR: OAuth server error: 1 validation error for Settings
HOMEASSISTANT_TOKEN
  Value error, Home Assistant token must be provided [type=value_error, input_value='', input_type=str]
    For further information visit https://errors.pydantic.dev/2.12/v/value_error

🖥️ Client Application

Claude Desktop

📦 Installation Method

Docker (ghcr.io/homeassistant-ai/ha-mcp)

💻 Operating System

Linux

OS Version

Debian 13

📖 Setup Guide Followed

https://github.com/homeassistant-ai/ha-mcp/blob/master/docs/OAUTH.md

🔄 Exact Steps You Followed

Follow setup docs on https://github.com/homeassistant-ai/ha-mcp/blob/master/docs/OAUTH.md

🐍 Python Version

No response

📦 ha-mcp Version

No response

🏠 Home Assistant Version

No response

💡 Additional Context

No response

[github-actions]

🔍 Analysis

The issue is caused by a conflict between the Docker image's default environment variables and the application's configuration validation logic. The Dockerfile for ha-mcp defines HOMEASSISTANT_TOKEN="" as a default. When the server starts, Pydantic's Settings class picks up this empty string from the environment, which overrides the internal default sentinel value ("oauth-mode-token").

Even when running in OAuth mode—where a server-side token is not required—the application still initializes the global settings. The homeassistant_token validator in src/ha_mcp/config.py is currently strictly configured to reject empty strings, leading to the validation error reported.

This appears to be a regression or an oversight introduced when standardizing the Settings class, as it doesn't account for environments (like Docker) that might provide empty strings for optional variables.

🛠️ Suggested Steps

1. Temporary Workaround: Set a dummy value for HOMEASSISTANT_TOKEN in your Docker command. Since you are in OAuth mode, this token will not be used, but it will satisfy the startup validation.

   docker run -d -p 8086:8086 \
     -e HOMEASSISTANT_URL=https://your-ha.example.com \
     -e HOMEASSISTANT_TOKEN=unused \
     -e MCP_BASE_URL=https://your-mcp.example.com \
     ghcr.io/homeassistant-ai/ha-mcp:latest ha-mcp-oauth

2. Verify Environment: Ensure you don't have a .env file in the directory where you are running Docker that might be setting HOMEASSISTANT_TOKEN to an empty value.
3. Wait for Fix: A fix is proposed below to handle empty strings gracefully in the configuration loader.

📊 Technical Analysis (for maintainers)

Root Cause

The Dockerfile contains ENV HOMEASSISTANT_TOKEN="". Pydantic's BaseSettings prioritizes environment variables over class defaults. In src/ha_mcp/config.py, the homeassistant_token field has a validator that raises ValueError if the value is empty. While main_oauth correctly identifies that a token isn't needed, it still instantiates HomeAssistantSmartMCPServer, which in turn triggers the global Settings validation before the server can start.

Affected Code

• src/ha_mcp/config.py: The Settings class and its validate_homeassistant_token method.
• Dockerfile: The default ENV values that trigger this state.

Proposed Fix

Modify src/ha_mcp/config.py to add "before" validators that convert empty strings (often provided by Docker or shells) into the appropriate OAuth sentinel values. This allows the model to initialize, while the existing _validate_standard_credentials check in __main__.py will still correctly catch missing credentials for non-OAuth modes.

--- a/src/ha_mcp/config.py
+++ b/src/ha_mcp/config.py
@@ -107,6 +107,18 @@
     @property
     def env_file_name(self) -> str:
         """Get the current environment file name."""
         return os.getenv("HAMCP_ENV_FILE", ".env")
 
+    @field_validator("homeassistant_url", mode="before")
+    @classmethod
+    def _validate_url_empty(cls, v: Any) -> Any:
+        """Handle empty URL from environment (e.g. Docker)."""
+        return OAUTH_MODE_URL if v == "" else v
+
+    @field_validator("homeassistant_token", mode="before")
+    @classmethod
+    def _validate_token_empty(cls, v: Any) -> Any:
+        """Handle empty token from environment (e.g. Docker)."""
+        return OAUTH_MODE_TOKEN if v == "" else v
+
     @field_validator("homeassistant_url")

Related Issues/PRs

• No similar issues found in recent history.

---

🤖 Automated analysis by Issue Bot

[github-actions]

✅ This issue has been addressed in the dev channel!

A fix for this issue has been merged to master (PR #893) and is available for testing in the dev channel.

Test the fix before the next stable release (biweekly Wednesday):
📖 Dev Channel Documentation

Quick start

# Run dev version
uvx ha-mcp-dev

# Check version
uvx ha-mcp-dev --version

Docker:

docker pull ghcr.io/homeassistant-ai/ha-mcp:dev
docker run --rm -i \
  -e HOMEASSISTANT_URL=http://your-ha:8123 \
  -e HOMEASSISTANT_TOKEN=your_token \
  ghcr.io/homeassistant-ai/ha-mcp:dev

---

After testing:

• ✅ If it's fixed: Great! Feel free to comment here to confirm
• ❌ If still broken: Open a new issue and reference [BUG] OAuth still requires HOMEASSISTANT_TOKEN #886
  • Closed issues can't be reopened by reporters
  • A new issue helps us track the problem properly