XiaoZhi Local Deployment Guide

English | 简体中文

A practical, step-by-step bilingual guide for deploying XiaoZhi (小智) — the open-source AI voice assistant — on your own hardware and server. It covers the whole local deployment workflow: server deployment, LLM / ASR / TTS configuration, firmware build & flash, MCP extension, digital human module, and troubleshooting.

What is XiaoZhi?

XiaoZhi is an open-source AI voice assistant ecosystem:

• ESP32 device (firmware) — captures audio, detects the wake word offline, plays replies, and shows status on a display
• xiaozhi-server — handles speech recognition (ASR), LLM conversation, text-to-speech (TTS), OTA, and MCP tool management
• LLM API — Qwen, DeepSeek, or any OpenAI-compatible model
• MCP endpoint (optional) — connects external tools (calculator, weather, smart home, ...) to your assistant
• Digital human module (optional) — browser-based avatar page with local wake-word runtime for testing/display

System Architecture

ESP32 device (firmware)  ⇄ WebSocket ⇄ xiaozhi-server (ASR + LLM + TTS)  → LLM API
                                        ⇄ MCP ⇄ mcp-endpoint-server → custom tools
                                        ⇄ digital-human (browser test page)

Table of Contents

#	Chapter	章节
1	Deployment Overview	部署方式总览
2	Server Deployment	服务器端部署
3	MCP Endpoint Deployment	MCP 接入点部署
4	Adding MCP Features	给小智接入 MCP 功能
5	Firmware Build & Flash	固件编译与烧录
6	LLM & Voice Configuration	大模型与语音配置
7	FAQ	常见问题 FAQ
8	Digital Human Module	数字人模块
9	Common Errors & Screenshots	常见报错与截图

Recommended Path

1. Deploy the server (Chapter 2)
2. Configure the LLM (Chapter 6)
3. Build and flash the firmware (Chapter 5)
4. Provision Wi-Fi and start talking
5. Extend with MCP tools (Chapters 3 & 4) or the digital human module (Chapter 8)

Upstream Projects

• 78/xiaozhi-esp32 — ESP32 firmware
• xinnan-tech/xiaozhi-esp32-server — voice server
• xinnan-tech/mcp-endpoint-server — MCP endpoint server
• 78/mcp-calculator — MCP calculator example

License

MIT — see LICENSE.