Installation

Phoenix MCP runs entirely inside Home Assistant. There is no extra process and no cloud dependency, so installation is the same as any other custom integration: add the files, restart, add the integration.

Requirements

Home Assistant: 2024.5.0 or later. HACS reads this minimum from hacs.json, but it is not enforced at runtime or pinned in the integration manifest. The automated test suite runs against current Home Assistant (the version pinned by the test harness, 2026.x at the time of writing), so recent versions are what is continuously verified; the 2024.5 floor reflects the APIs Phoenix MCP uses but is not re-tested every release.
Instances: One Phoenix MCP instance per Home Assistant. The config flow will not let you add a second.
Dependencies: None beyond what Home Assistant already ships. No Python packages to install.

Install through HACS

HACS is the recommended path because it handles updates for you.

Open custom repositories

In HACS, go to Integrations and open the menu in the top-right corner. Choose Custom repositories.

Add the repository

Enter the repository URL and select Integration as the category, then click Add.

https://github.com/leecaochang/phoenix-mcp

HACS custom repositories dialog with the Phoenix MCP repository URL entered and Integration selected — Adding the repository in HACS.

Install and restart

Find Phoenix MCP in the HACS integration list, install it, then restart Home Assistant.

Install manually

If you prefer not to use HACS, copy the integration into your config directory.

Copy the integration folder

Place the custom_components/phoenix_mcp folder into your Home Assistant config directory.

<config>/custom_components/phoenix_mcp/

Restart Home Assistant

Restart so Home Assistant discovers the new integration.

Set up the integration

Add the integration

Go to Settings > Devices & services > Add integration and search for Phoenix MCP.

Home Assistant Add Integration dialog showing the Phoenix MCP result — Searching for Phoenix MCP.

Complete the config flow

Click through the single-step config flow. There is nothing to configure here; all management happens in the panel.

Open the Phoenix MCP panel

Open the Phoenix MCP entry in your Home Assistant sidebar. This is where you create tokens, scope permissions, and read the audit log.

Everything lives in the panel

Phoenix MCP has no YAML configuration and no options flow. Once the integration is added, the sidebar panel is the only place you manage it.

Migrating from the native HA MCP server?

Phoenix MCP replaces it entirely. Once you have created a token and pointed your AI client at /api/phoenix-mcp, you can disable or remove the native MCP integration from Settings > Devices & services. The client configuration changes in two places: the URL, and the bearer value, which becomes the phx_ token (a Home Assistant long-lived access token is not accepted). The tool names and parameters are identical.