xiaozhi-esp32
本项目为xiaozhi-esp32提供后端服务，帮助您快速搭建ESP32设备控制服务器。Backend service for xiaozhi-esp32, helps you quickly build an ESP32 device control server.
claude mcp add --transport stdio xinnan-tech-xiaozhi-esp32-server docker run -i xiaozhi-esp32-server:latest \ --env XOAI_LOG_LEVEL="info" \ --env XOAI_CONFIG_PATH="/app/config/config.yaml"
How to use
The xiaozhi-esp32 MCP server provides backend capabilities for the Xiaozhi ESP32 ecosystem. It exposes MQTT/UDP bridges, WebSocket endpoints, an MCP access point, voice/dialect features, and a knowledge base to support interactions with ESP32 devices and related services. You can connect client applications or device gateways to the MCP server via the supported protocols, authenticate as needed, and then use the provided endpoints to send commands, query knowledge, or trigger actions on connected devices. The server integrates with various components such as ASR/LLM modules, a local or remote knowledge base, and can operate in simplified single-agent mode or in a multi-agent setup depending on deployment requirements.
How to install
Prerequisites:\n- Docker or Docker Compose installed on the host\n- Basic familiarity with running containerized services\n- Network access for MQTT/WS endpoints used by your Esp32 devices\n\nBasic Docker deployment:\nbash\n# Pull and run the MCP server image (latest release)\ndocker pull xiaozhi-esp32-server:latest\n\ndocker run -d --name xiaozhi-esp32-mcp \\n -p 1883:1883 \\n -p 8883:8883 \\n -p 8080:8080 \\n -e XOAI_LOG_LEVEL=info \\n -e XOAI_CONFIG_PATH=/app/config/config.yaml \\n xiaozhi-esp32-server:latest\n\n- If you prefer docker-compose, create a docker-compose.yaml with the service definition and run docker-compose up -d\n\nAlternative: Native installation (if provided in repo examples)\n- Ensure Python/Java/Vue toolchains are installed as per the repo guidelines\n- Follow the repository’s native setup scripts to install dependencies and start the server.\n
Additional notes
Tips and common issues:\n- Ensure that the Docker image name matches the published image tag in your environment. If the image is private, log in to the registry first.\n- Configure environment variables (such as LOG level and config path) to meet your deployment needs.\n- For MQTT/WebSocket endpoints, ensure firewall rules allow the required ports (default 1883 for MQTT, 8080 for HTTP/WebSocket, 8883 for MQTT over TLS).\n- When deploying in production, consider persisting data (e.g., knowledge base, configurations) to a database or mounted volume as appropriate.\n- If you encounter protocol mismatch with ESP32 devices, verify the Xiaozhi protocol version compatibility between the ESP32 firmware and the MCP server.\n
