xiaozhi-mcp-ha

Xiaozhi MCP Integration for Home Assistant

A Home Assistant Custom Integration (HACS) that connects Xiaozhi ESP32 AI chatbot to Home Assistant via MCP (Model Context Protocol).

Features

• 🤖 Connect Xiaozhi ESP32 devices to Home Assistant
• 🔌 Full MCP (Model Context Protocol) support for AI-powered home automation
• 🏠 Control Home Assistant entities through natural language
• 🔒 Secure authentication with long-lived access tokens
• 🔄 Automatic reconnection with exponential backoff
• 📊 Real-time status monitoring and logging
• 🛠️ Easy configuration through Home Assistant UI
• 🌐 Support for both WebSocket and HTTP endpoints

What is Xiaozhi?

Xiaozhi is an open-source ESP32-based AI chatbot that uses voice interaction and MCP protocol to control various smart home devices and services. It supports multiple ESP32 platforms and can integrate with various AI models like Qwen and DeepSeek.

• All-in-one hardware: ESP32-S3 (16 MB flash / 8 MB PSRAM), digital mic, speaker with class-D amp and 1.28–1.85″ colour LCD.
• Local wake word + cloud intelligence: an offline wake-word engine runs on the device; after activation audio is sent to Xiaozhi’s servers where ASR, LLM reasoning (Qwen, DeepSeek, Doubao …), and TTS are performed.
• Voice-only Home-Assistant control: this HACS integration connects the device to Home Assistant MCP, letting you toggle lights, scenes and more entirely by voice.
• Many shapes, same guts: boards are sold as square dev-kits, cubes, pucks and the cute “Astronaut Ball” shown above – all share the same firmware stack.
• Ultra-low cost: the Astronaut Ball costs ≈ USD 19 – cheaper than most bare ESP32 kits. AliExpress product page

Requirements

• Home Assistant 2024.1.0 or later
• HACS (Home Assistant Community Store)
• Home Assistant MCP Server Integration (must be installed first)
• Xiaozhi ESP32 device or compatible hardware
• Active internet connection for MCP communication

Installation

Prerequisites: Install Home Assistant MCP Server

Before installing this integration, you must install the official Home Assistant MCP Server integration:

1. Go to Settings > Devices & Services > Add Integration
2. Search for "Model Context Protocol Server" (or "MCP Server")
3. Install and configure the MCP Server integration
4. The MCP server will run locally within your Home Assistant instance at http://localhost:8123/mcp_server/sse
5. Make sure to configure entity exposure in the MCP Server settings

HACS Installation (Recommended)

1. Open HACS in Home Assistant
2. Click on "Integrations"
3. Click the three dots in the top right corner
4. Select "Custom repositories"
5. Add this repository URL: https://github.com/mac8005/xiaozhi-mcp-ha
6. Set category to "Integration"
7. Click "Add"
8. Search for "Xiaozhi MCP" and install
9. Restart Home Assistant

Manual Installation

1. Download the xiaozhi_mcp folder from this repository
2. Copy it to config/custom_components/xiaozhi_mcp/ in your Home Assistant installation
3. Restart Home Assistant

Configuration

Step 1: Create Long-Lived Access Token

1. Go to your Home Assistant Profile: Settings > People > Users > Click on your user
2. Scroll down to "Long-lived access tokens"
3. Click "Create Token"
4. Give it a name like "Xiaozhi MCP"
5. Copy the token (you won't see it again!)

Step 2: Get Xiaozhi MCP Endpoint

1. Visit xiaozhi.me and create an account
2. Go to the MCP section in your dashboard
3. Copy your MCP endpoint URL

Step 3: Configure Integration

1. Go to Settings > Devices & Services > Add Integration
2. Search for "Xiaozhi MCP"
3. Enter your configuration:
   • Name: Friendly name for the integration
   • Xiaozhi MCP Endpoint: Your xiaozhi.me MCP endpoint URL
   • Long-Lived Access Token: Token created in Step 1
   • Scan Interval: How often to check connection status (default: 30 seconds)
   • Enable Logging: Enable detailed logging for debugging

How It Works

This integration acts as a bridge/proxy between your Xiaozhi ESP32 device and the official Home Assistant MCP Server:

1. Xiaozhi ESP32 connects to the Xiaozhi cloud service
2. Xiaozhi cloud sends MCP requests to this integration via WebSocket
3. This integration forwards the MCP requests to the local Home Assistant MCP Server via Server-Sent Events (SSE)
4. Home Assistant MCP Server (at http://localhost:8123/mcp_server/sse) processes the requests and controls your Home Assistant entities
5. Responses are sent back through the same chain

[Xiaozhi ESP32] ←→ [Xiaozhi Cloud] ←→ [This Integration] ←→ [HA MCP Server] ←→ [Home Assistant]
                                         (MCP Proxy)      (SSE: /mcp_server/sse)

Key Architecture Points:

• ✅ No MCP Server Reimplementation: This integration does NOT implement its own MCP server
• ✅ Uses Official MCP Server: All MCP functionality is provided by the official Home Assistant MCP Server integration
• ✅ Acts as SSE Proxy: This integration forwards MCP messages to the official MCP server via Server-Sent Events
• ✅ Secure Local Communication: All Home Assistant communication happens locally through the official MCP server
• ✅ No External URLs Required: No need to expose your Home Assistant instance to the internet

Usage

Once configured, your Xiaozhi device can:

• Control lights: "Turn on the living room lights"
• Check sensors: "What's the temperature in the bedroom?"
• Control climate: "Set the thermostat to 72 degrees"
• Run automations: "Activate movie mode"
• Get device status: "Is the front door locked?"

Configuration Options

Option	Description	Required	Default
name	Friendly name for the integration	Yes	-
xiaozhi_endpoint	Xiaozhi MCP endpoint URL	Yes	-
access_token	Long-lived access token	Yes	-
scan_interval	Status check interval (seconds)	No	30
enable_logging	Enable detailed logging	No	False

Troubleshooting

Important Notes

• Critical Dependency: This integration requires the official Home Assistant MCP Server integration to be installed and running
• No MCP Server Reimplementation: This integration does NOT implement its own MCP server - it only acts as a proxy
• SSE Communication: Uses Server-Sent Events to communicate with the MCP Server at http://localhost:8123/mcp_server/sse
• Entity Exposure: Make sure to expose the entities you want to control via the MCP Server settings in Home Assistant
• Local Communication: All Home Assistant communication happens locally through the official MCP server
• No External URLs: No need to configure external Home Assistant URLs or expose your instance to the internet

Debug Logging

Enable debug logging by adding to configuration.yaml:

logger:
  default: info
  logs:
    custom_components.xiaozhi_mcp: debug

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

☕ Support Development

If this project helps you, consider supporting its development! Your support helps maintain and improve this integration.

All donations are appreciated and help keep this project active! 🙏

Contributing

Contributions are welcome! Please read the Contributing Guide for details on how to contribute to this project.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Thanks to 78/xiaozhi-esp32 for the original Xiaozhi project
• Thanks to the Home Assistant community for the excellent platform

Related Projects

• Xiaozhi ESP32 - The original Xiaozhi project
• MCP Calculator - MCP sample implementation
• Home Assistant MCP Server - Official HA MCP Server integration
• Home Assistant - Open source home automation platform

---