Provides scoped, least-privilege access to Home Assistant entities, with per-client tokens, capabilities, rate limits, optional expiry, built-in auditing, instant token revocation, a per-entity semantic safety layer (MESA), and a catalog of 131 tools for reading, controlling, and authoring Home Assistant configuration.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Phoenix MCP Turn off the living room lights and set the thermostat to 68."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
English | Español | Français | Deutsch | Nederlands | Polski | 简体中文 | 繁體中文 | 日本語 | 한국어 | Русский
Phoenix MCP gives your AI agents scoped, least-privilege access to Home Assistant. Each client gets its own token, limited to exactly the entities you allow, with its own capabilities, rate limit, and optional expiry. Auditing is enabled by default and configurable per outcome, any token can be revoked instantly, and the per-entity semantic safety layer (MESA) can make a device confirm-only or off-limits by its nature, no matter what permissions a token is granted.
Phoenix MCP runs entirely inside Home Assistant, with no extra process, no cloud dependency in the core server, and no setup beyond the Phoenix MCP panel (the optional Agent Chat, voice, and AI Task features send conversations to the model provider you configure, unless you point them at a local Ollama). It works with the MCP clients you already use (Claude Code, Cursor, ChatGPT/Codex, Gemini, and others), or you can skip installing a client altogether and chat from inside Home Assistant itself. Either way, a guided setup takes you from a new token to a working agent in minutes, backed by a catalog of 160 tools for reading, controlling, and authoring your configuration. The panel is available in multiple languages, follows your Home Assistant profile language by default, and falls back to English when that language is unavailable.
The panel currently supports English, Spanish, French, German, Dutch, Polish, Russian, Simplified Chinese, Traditional Chinese, Korean, and Japanese. To change the panel language manually, open Phoenix MCP > Settings > Language and choose a language. Choose Auto to follow your Home Assistant profile language again.
Related MCP server: Home Assistant MCP Server (HA-mcp)
The full documentation, including the tool reference, permissions, capabilities, MESA, and the admin API, is at leecaochang.github.io/phoenix-mcp. The panel's help links point there.
New here? Start with the Quick start: it creates your first token, grants it one device, then lets you choose whether to chat from inside Home Assistant or connect an external agent, in a few minutes either way.
Home Assistant 2025.2.0 or later.
One Phoenix MCP instance per Home Assistant. No Python dependencies beyond what HA ships.
In HACS, open Integrations, then the top-right menu, and choose Custom repositories.
Enter https://github.com/leecaochang/phoenix-mcp and select Integration as the category, then click Add.
Find Phoenix MCP in the HACS integration list, install it, and restart Home Assistant.
Prefer to install by hand? Copy the custom_components/phoenix_mcp folder into your Home Assistant config directory under custom_components/phoenix_mcp, then restart.
Go to Settings > Devices & services > Add integration and search for Phoenix MCP. Click through the single-step config flow, then open the Phoenix MCP panel in your sidebar. The Quick start takes it from there.
Report issues at github.com/leecaochang/phoenix-mcp/issues.
This server cannot be deployed
OAuth 2.1 short-link tools for AI agents with scoped tokens, approvals, audit logs, and revocation.
Give your AI agents the tools to build, manage, and run automation workflows.
Connect AI agents to 1000+ apps with managed authentication and tool-calling.
Verified, pay-per-use API tools for AI agents through one authenticated connection.
