Xiaozhi ESP32
本项目为xiaozhi-esp32提供后端服务，帮助您快速搭建ESP32设备控制服务器。Backend service for xiaozhi-esp32, helps you quickly build an ESP32 device control server.
What is Xiaozhi ESP32?
Xiaozhi ESP32 is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to 本项目为xiaozhi-esp32提供后端服务，帮助您快速搭建esp32设备控制服务器。backend service for xiaozhi-esp32, helps you quickly build an esp32 device control server.
本项目为xiaozhi-esp32提供后端服务，帮助您快速搭建ESP32设备控制服务器。Backend service for xiaozhi-esp32, helps you quickly build an ESP32 device control server.
This server falls under the Cloud Services category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- 本项目为xiaozhi-esp32提供后端服务，帮助您快速搭建ESP32设备控制服务器。Backend service
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx xiaozhi-esp32Configuration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Xiaozhi ESP32
Xiaozhi ESP32 is a backend service for ESP32-based AI chatbot devices, providing the server infrastructure needed to connect ESP32 hardware to large language models such as Qwen and DeepSeek via WebSocket or MQTT+UDP. The project enables offline voice wake-up, streaming speech recognition, LLM processing, and text-to-speech on 70+ ESP32 hardware platforms including ESP32-C3, S3, and P4. It is used by makers and embedded developers who want to build low-cost, voice-interactive AI devices with support for smart home control, web search, and email capabilities through the xiaozhi.me platform and MCP tool integrations.
Prerequisites
- An ESP32 development board (ESP32-C3, S3, or P4 recommended; 70+ hardware platforms supported)
- ESP-IDF SDK 5.4 or later installed for custom firmware builds (or use pre-built firmware for beginners)
- A registered account on xiaozhi.me for cloud configuration and free Qwen model access
- Wi-Fi credentials for the ESP32 device to connect to the internet
- Optional: a community server (Python, Java, or Go) for self-hosted deployments
Flash pre-built firmware to your ESP32 device
For beginners, download the pre-built firmware from the releases page and flash it using the ESP Flash Tool or esptool. This connects the device to xiaozhi.me by default without any development environment setup.
# Flash with esptool (replace PORT and FIRMWARE_FILE)
pip install esptool
esptool.py --port /dev/ttyUSB0 write_flash 0x0 xiaozhi-esp32-firmware.binRegister on xiaozhi.me and configure your device
Create a free account at xiaozhi.me. After flashing, the device will appear in your console where you can configure the LLM model (Qwen real-time by default), voice wake word, language, and MCP tool integrations.
Set up a self-hosted backend (advanced)
If you want to run your own server instead of using xiaozhi.me, choose one of the community implementations and configure the device firmware to point to your server's WebSocket endpoint.
# Example: Python community server
git clone https://github.com/xinnan-liu/xiaozhi-esp32-server
cd xiaozhi-esp32-server
pip install -r requirements.txt
python main.pyBuild custom firmware with ESP-IDF (advanced)
For custom wake words, fonts, emojis, or hardware support, set up the ESP-IDF development environment. Linux is recommended for compilation speed.
# Clone the firmware repository
git clone https://github.com/78/xiaozhi-esp32
cd xiaozhi-esp32
# Set up ESP-IDF environment
. $IDF_PATH/export.sh
# Build and flash
idf.py build flash monitorWake the device and start a conversation
Once flashed and configured, say the wake word (default: 'Xiao Zhi') to activate the voice assistant. The device streams audio to the backend, gets an LLM response, and speaks the answer via TTS.
Xiaozhi ESP32 Examples
Client configuration
Example device configuration structure for pointing an ESP32 to a self-hosted backend server instead of xiaozhi.me.
{
"server": {
"websocket_url": "ws://your-server-ip:8765",
"protocol": "websocket"
},
"audio": {
"codec": "opus",
"sample_rate": 16000
},
"language": "en",
"wake_word": "Xiao Zhi"
}Prompts to try
Voice commands and interactions supported by the Xiaozhi ESP32 AI chatbot with MCP tool integrations.
- "Xiao Zhi, what's the weather today?" (triggers web search tool)
- "Xiao Zhi, turn on the living room lights" (triggers smart home control via MCP)
- "Xiao Zhi, what time is it in Tokyo?"
- "Xiao Zhi, send an email to John saying the meeting is at 3pm" (email tool)
- "Xiao Zhi, search the web for the latest AI news"Troubleshooting Xiaozhi ESP32
Device connects to Wi-Fi but cannot reach the xiaozhi.me server
Verify your router allows outbound WebSocket connections (port 443 for wss://). Check the device serial output with 'idf.py monitor' for connection error codes. Ensure the device firmware version matches the server API version.
Voice wake word is not detected reliably
ESP-SR wake word detection is sensitive to microphone placement and ambient noise. Ensure the microphone is unobstructed and try reducing background noise. For custom wake words, use the Assets Generator tool on xiaozhi.me to train a personalized model.
Build fails with ESP-IDF version errors
The project requires ESP-IDF 5.4 or later. Run 'idf.py --version' to check your installed version and follow the ESP-IDF install guide at docs.espressif.com to upgrade. Ensure you source the correct export.sh for your IDF path.
Frequently Asked Questions about Xiaozhi ESP32
What is Xiaozhi ESP32?
Xiaozhi ESP32 is a Model Context Protocol (MCP) server that 本项目为xiaozhi-esp32提供后端服务，帮助您快速搭建esp32设备控制服务器。backend service for xiaozhi-esp32, helps you quickly build an esp32 device control server. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Xiaozhi ESP32?
Follow the installation instructions on the Xiaozhi ESP32 GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Xiaozhi ESP32?
Xiaozhi ESP32 works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Xiaozhi ESP32 free to use?
Yes, Xiaozhi ESP32 is open source and available under the MIT license. You can use it freely in both personal and commercial projects.
Xiaozhi ESP32 Alternatives — Similar Cloud Services Servers
Looking for alternatives to Xiaozhi ESP32? Here are other popular cloud services servers you can use with Claude, Cursor, and VS Code.
Open WebUI
★ 138.2kUser-friendly AI Interface (Supports Ollama, OpenAI API, ...)
Anything LLM
★ 60.4kThe all-in-one AI productivity accelerator. On device and privacy first with no annoying setup or configuration.
LocalAI
★ 46.4kLocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.
Nacos
★ 33.0kan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.
Gateway
★ 11.8kA blazing fast AI Gateway with integrated guardrails. Route to 1,600+ LLMs, 50+ AI Guardrails with 1 fast & friendly API.
Nginx UI
★ 11.2kYet another WebUI for Nginx
Browse More Cloud Services MCP Servers
Explore all cloud services servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Xiaozhi ESP32 in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Xiaozhi ESP32?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.