# Phoenix MCP

[![HACS](https://github.com/leecaochang/Phoenix-MCP/actions/workflows/hacs.yml/badge.svg)](https://github.com/leecaochang/Phoenix-MCP/actions/workflows/hacs.yml)
[![Hassfest](https://github.com/leecaochang/Phoenix-MCP/actions/workflows/hassfest.yml/badge.svg)](https://github.com/leecaochang/Phoenix-MCP/actions/workflows/hassfest.yml)
[![Tests](https://github.com/leecaochang/Phoenix-MCP/actions/workflows/tests.yml/badge.svg)](https://github.com/leecaochang/Phoenix-MCP/actions/workflows/tests.yml)
[![HACS Custom](https://img.shields.io/badge/HACS-Custom-41BDF5.svg)](https://hacs.xyz)
[![Home Assistant](https://img.shields.io/badge/Home%20Assistant-2026.7%2B-41BDF5?logo=home-assistant&logoColor=white)](https://www.home-assistant.io)


**English** | [Español](README.es.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Deutsch](README.de.md) | [Nederlands](README.nl.md) | [Polski](README.pl.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-Hant.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Русский](README.ru.md) | [Svenska](README.sv.md) | [Dansk](README.da.md) | [Norsk Bokmål](README.nb.md) | [Suomi](README.fi.md)

Phoenix MCP gives your AI agents scoped, least-privilege access to Home Assistant. Each client gets its own access key, 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 access key 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 an access key is granted. Advisory is the default MESA mode: most policy restrictions warn until Enforced is selected; read-only nature and explicit privacy denials still block.

Phoenix MCP runs entirely inside Home Assistant, with no separate service to deploy, 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 access key to a working agent in minutes, backed by a catalog of 169 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. Home Companion and optional decision routing can also send requests and scoped results to a hosted provider. External MCP clients follow their own provider and data-sharing settings.

## Languages

The panel currently supports English, Spanish, French, Italian, German, Dutch, Polish, Russian, Simplified Chinese, Traditional Chinese, Korean, Japanese, Swedish, Danish, Norwegian, and Finnish. 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.

## Documentation

The full documentation, including the tool reference, permissions, capabilities, MESA, and the admin API, is at **[leecaochang.github.io/Phoenix-MCP](https://leecaochang.github.io/Phoenix-MCP/)**. The panel's help links point there.

New here? Start with the **[Quick start](https://leecaochang.github.io/Phoenix-MCP/quickstart.html)**: it creates your first access key, 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.

## Requirements

- Home Assistant 2026.7.0 or later.
- One Phoenix MCP instance per Home Assistant. Home Assistant installs the Python requirements `Babel>=2.18.0`, `jsonschema>=4.26.0` under its dependency constraints; MESA is bundled with Phoenix MCP.

## Install via HACS

1. In HACS, open the top-right menu and choose **Custom repositories**.
2. Enter `https://github.com/leecaochang/Phoenix-MCP` and select **Integration** as the category, then click **Add**.
3. 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.

### Set up

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](https://leecaochang.github.io/Phoenix-MCP/quickstart.html) takes it from there.

## Issues and feedback

Report issues at [github.com/leecaochang/Phoenix-MCP/issues](https://github.com/leecaochang/Phoenix-MCP/issues).