基于MCP的聊天机器人

(英语 | 中文 | 日语)

简介

👉 人类：给AI一台相机 vs AI：瞬间发现主人三天没洗头【bilibili】

👉 亲手打造你的AI女友，新手指南【bilibili】

作为一款语音交互设备，小智AI聊天机器人利用通义千问、DeepSeek等大模型的AI能力，并通过MCP协议实现多终端控制。

版本说明

当前v2版本与v1分区表不兼容，因此无法通过OTA方式从v1升级到v2。有关分区表的详细信息，请参阅partitions/v2/README.md。

所有运行v1的硬件都可以通过手动刷写固件升级到v2。

v1的稳定版本为1.9.2。您可以通过运行git checkout v1切换到v1版本。v1分支将一直维护到2026年2月。

已实现的功能

• Wi‑Fi / ML307 Cat.1 4G
• 离线语音唤醒 ESP‑SR
• 支持两种通信协议（Websocket 或 MQTT+UDP）
• 使用OPUS音频编解码器
• 基于流式ASR + LLM + TTS架构的语音交互
• 说话人识别，可识别当前说话人 3D Speaker
• OLED / LCD显示屏，支持表情符号显示
• 电池电量显示及电源管理
• 多语言支持（中文、英文、日文）
• 支持ESP32‑C3、ESP32‑S3、ESP32‑P4芯片平台
• 设备端MCP用于设备控制（扬声器、LED、舵机、GPIO等）
• 云端MCP扩展大模型能力（智能家居控制、PC桌面操作、知识搜索、邮件等）
• 可在线网页编辑自定义唤醒词、字体、表情符号和聊天背景（Custom Assets Generator）

硬件

面包板DIY实践

请参阅飞书文档教程：

👉 "小智AI聊天机器人百科"

面包板演示：

支持70余款开源硬件（部分列表）

• LiChuang ESP32‑S3开发板
• Espressif ESP32‑S3‑BOX3
• M5Stack CoreS3
• M5Stack AtomS3R + Echo Base
• Magic Button 2.4
• Waveshare ESP32‑S3‑Touch‑AMOLED‑1.8
• LILYGO T‑Circle‑S3
• XiaGe Mini C3
• CuiCan AI吊坠
• WMnologo‑Xingzhi‑1.54TFT
• SenseCAP Watcher
• ESP‑HI低成本机器狗

软件

固件刷写

对于初学者，建议使用无需搭建开发环境即可刷写的固件。

该固件默认连接到官方xiaozhi.me服务器。个人用户可以注册账号免费使用通义千问实时模型。

👉 新手固件刷写指南

开发环境

• Cursor 或 VSCode
• 安装ESP‑IDF插件，选择SDK版本5.4及以上
• Linux相比Windows编译速度更快且驱动问题更少
• 本项目采用Google C++代码风格，请在提交代码时确保符合规范

开发者文档

• 自定义主板指南 - 学习如何为小智AI创建自定义主板
• MCP协议物联网控制使用指南 - 学习如何通过MCP协议控制物联网设备
• MCP协议交互流程 - 设备端MCP协议实现
• MQTT + UDP混合通信协议文档
• 详细的WebSocket通信协议文档

大模型配置

如果您已经拥有小智AI聊天机器人设备并已连接到官方服务器，您可以登录xiaozhi.me控制台进行配置。

👉 后端操作视频教程（旧界面）

相关开源项目

如需在个人电脑上部署服务器，请参考以下开源项目：

• xinnan-tech/xiaozhi-esp32-server Python服务器
• joey-zhou/xiaozhi-esp32-server-java Java服务器
• AnimeAIChat/xiaozhi-server-go Golang服务器
• hackers365/xiaozhi-esp32-server-golang Golang服务器

其他使用小智通信协议的客户端项目：

• huangjunsen0406/py-xiaozhi Python客户端
• TOM88812/xiaozhi-android-client 安卓客户端
• 100askTeam/xiaozhi-linux 由100ask提供的Linux客户端
• 78/xiaozhi-sf32 四川团队开发的蓝牙芯片固件
• QuecPython/solution-xiaozhiAI 由移远通信提供的QuecPython固件

自定义资源工具：

• 78/xiaozhi-assets-generator 自定义资源生成器（唤醒词、字体、表情符号、背景）

关于项目

这是一个基于ESP32的开源项目，采用MIT许可证发布，允许任何人免费使用，包括用于商业用途。我们希望该项目能够帮助大家理解AI硬件开发，并将快速发展的大型语言模型应用到实际硬件设备中。如果您有任何想法或建议，欢迎随时提交Issue，或加入我们的Discord及QQ群：994694848。

星标历史

xiaozhi-esp32 快速上手指南

小智 (xiaozhi-esp32) 是一款基于 MCP 协议的开源 AI 语音聊天机器人项目，支持 ESP32-C3/S3/P4 系列芯片。它结合大模型（如通义千问、DeepSeek）实现流式语音交互，并可通过 MCP 协议控制本地硬件或扩展云端能力。

环境准备

系统要求

• 操作系统：推荐 Linux（编译速度快、驱动问题少），Windows 或 macOS 也可用。
• 开发工具：VSCode 或 Cursor 编辑器。
• SDK 版本：ESP-IDF v5.4 或以上版本。

前置依赖

1. 安装 Git。
2. 安装 ESP-IDF 框架及对应插件：
   • 访问 ESP-IDF 官方文档 完成安装。
   • 在 VSCode/Cursor 中安装 Espressif IDF 插件，并在设置中选择 SDK 版本 5.4+。
3. 确保电脑已安装 Python 3.8+ 及相关依赖（ESP-IDF 安装过程通常会自动处理）。

提示：国内用户若遇到 Git 克隆慢的问题，可配置国内镜像源或使用代理加速。

安装步骤

1. 克隆项目代码

打开终端，执行以下命令拉取最新代码：

git clone https://github.com/78/xiaozhi-esp32.git
cd xiaozhi-esp32

注意：当前 v2 版本与 v1 分区表不兼容。若需使用稳定的 v1 版本，请执行 git checkout v1 切换分支。

2. 配置开发环境

在 VSCode/Cursor 中打开项目文件夹，点击底部状态栏的 ESP-IDF 插件按钮，选择：

• Configure ESP-IDF Extension
• 确保 SDK 版本指向 v5.4 或更高。

3. 编译与烧录

连接 ESP32 开发板到电脑，执行以下命令进行编译并烧录固件：

idf.py set-target esp32s3  # 根据实际芯片型号修改，如 esp32c3, esp32p4
idf.py flash monitor

• set-target：指定目标芯片型号（常见为 esp32s3）。
• flash：编译并烧录固件。
• monitor：烧录后自动打开串口监视器查看日志。

新手建议：若无开发环境，可直接使用官方提供的免编译固件进行烧录，参考 新手固件烧录指南。

基本使用

1. 连接网络

设备启动后，默认尝试连接 Wi-Fi。若需配置：

• 首次运行或通过串口发送配网指令（具体视硬件而定，部分开发板支持按键配网）。
• 支持 Wi-Fi 或 ML307 Cat.1 4G 模块联网。

2. 唤醒与对话

• 默认唤醒词：通常为“小智”（可在后台自定义）。
• 交互流程：
  1. 说出唤醒词，设备指示灯亮起或屏幕显示表情。
  2. 直接说话提问（例如：“今天天气怎么样？”）。
  3. 设备将通过云端大模型处理并语音回复。

3. 后台配置

固件默认连接官方服务器 xiaozhi.me。

1. 访问官网注册账号。
2. 登录控制台绑定设备 MAC 地址。
3. 免费使用通义千问实时模型，并可自定义唤醒词、音色、背景图等资源（可使用 资源生成器 制作）。

4. 进阶开发（可选）

若需私有化部署或自定义硬件控制：

• 自建服务端：参考 Python 版服务端 或其他语言版本。
• 自定义硬件：查阅 docs/custom-board.md 适配自己的电路板。
• MCP 控制：通过 MCP 协议控制 GPIO、舵机、LED 等外设，详见 docs/mcp-usage.md。