xiaozhi-esp32：基于 MCP 协议与 Qwen/DeepSeek 大模型的 ESP32 语音聊天机器人固件全解析

xiaozhi-esp32：基于 MCP 协议与 Qwen/DeepSeek 大模型的 ESP32 语音聊天机器人固件全解析

【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32

小智（xiaozhi-esp32）是一个由虾哥开源、以 MIT 许可证发布的 ESP32 语音聊天机器人固件项目。它把传统语音助手变成了一个基于 MCP（Model Context Protocol）的聊天机器人入口：设备端通过 WebSocket / MQTT 与后台通信，借助 Qwen、DeepSeek 等大模型的理解能力完成语音对话，再通过 MCP 协议把“语音”翻译成对硬件（音量、灯光、电机、GPIO）与云端服务（智能家居、PC 桌面、知识搜索、邮件）的精准控制。读完本文，你将理解该项目的整体架构、已实现的功能矩阵、MCP 在设备端的落地实现方式，以及从烧录固件到配置大模型、再到自定义板卡工具的完整实战路径。

小智 AI 通过 MCP 协议将大模型能力接入设备与云端，实现“说话即控制”的多端控制架构

项目定位：从“语音助手”到“MCP 聊天机器人”

小智 AI 聊天机器人的定位不是简单复刻一个智能音箱，而是作为一个语音交互入口：

• 用户通过语音与设备对话；
• 后台（云服务器）调用 Qwen / DeepSeek 等大模型的 AI 能力完成语义理解与回复生成；
• 大模型的“意图”通过MCP 协议转化为对设备端工具（Tool）的调用，实现多端控制。

换句话说，MCP 是这套系统里连接“AI 大脑”与“物理世界”的桥梁。项目在 README 中明确推荐所有新项目统一采用 MCP 协议进行物联网控制（见 docs/mcp-usage_zh.md）。

近期更新与工程现状

项目主线目前以 ESP-IDF v6.0 及更高版本为目标，仓库内提供 ESP-IDF 6.0 迁移文档 记录 SDK 兼容性、组件变更与板卡验证状态。README 中披露的工程现状包括：

• 首选稳定版为ESP-IDF v6.0.2；此前 157 个发布变体已在 v6.0.1 上通过构建验证，当前发布矩阵包含171 个变体，其中 170 个支持 IDF 6.0.x，ESP32-S31 变体需要 IDF 6.1 及以上版本；
• MQTT 与 BluFi 加密已迁移到PSA Crypto，同时完成 IDF 6 组件拆分及第三方依赖兼容处理；
• 加固了音频流水线并发、MQTT/UDP 数据包校验和发布矩阵选择逻辑；
• ESP-IDF v5.5 仅保留用于文档明确标注的旧版板卡。

已实现功能全景

README 中列出了非常完整的功能清单，可以归纳为以下几个维度：

关于自定义资源生成，项目配套提供了独立的 Assets 生成器工具（xiaozhi-assets-generator），可参考 scripts/build_default_assets.py 与 scripts/spiffs_assets/README.md 了解资源打包流程。

MCP 在设备端的落地：McpServer 实现剖析

README 将 MCP 作为项目的核心技术标签（项目描述即为 “An MCP-based Chatbot”）。在源码层面，MCP 由 main/mcp_server.h 与 main/mcp_server.cc 中的McpServer单例实现，协议参考 MCP 规范 2024-11-05 版本。

消息封装：JSON-RPC 2.0 作为内层负载

MCP 消息并不独立传输，而是封装在基础通信协议（WebSocket 或 MQTT）的消息体中。从 main/protocols/protocol.cc 可以看到SendMcpMessage的封装逻辑：

void Protocol::SendMcpMessage(const std::string& payload) { std::string message = "{\"session_id\":\"" + session_id_ + "\",\"type\":\"mcp\",\"payload\":" + payload + "}"; SendText(message); }

即外层消息结构为：

{ "session_id": "...", "type": "mcp", "payload": { "jsonrpc": "2.0", "method": "...", "params": { ... }, "id": ... } }

内层payload遵循标准 JSON-RPC 2.0：jsonrpc固定为"2.0"；id用于匹配请求与响应（设备响应时原样返回）；result表示成功结果；error表示失败信息。

支持的核心方法

McpServer::ParseMessage（main/mcp_server.cc）是设备端 MCP 的入口，解析并分派以下方法：

• initialize：初始化 MCP 会话。设备响应中携带protocolVersion: "2024-11-05"、capabilities.tools（空对象，具体工具需通过tools/list获取）以及serverInfo（设备名称取自BOARD_NAME，版本取自固件esp_app_get_description()）。
• tools/list：返回设备当前注册的全部工具及其inputSchema参数描述。支持cursor分页（单次响应负载上限约 8000 字节，超出时返回nextCursor供客户端继续请求），并支持withUserTools参数决定是否包含用户专属工具。
• tools/call：调用具体工具。参数按声明的类型（布尔 / 整数 / 字符串）做校验与取值，若缺少必填参数或参数超出范围则返回 JSON-RPC 错误；工具实际执行通过Application::Schedule调度到主线程完成，避免与音频等任务并发冲突（main/mcp_server.cc）。
• notifications/*：设备主动发送的通知（无id字段，后台不回复），代码在ParseMessage中对其直接忽略不处理。

工具的参数模型与返回值

从 main/mcp_server.h 可以看出设备端 MCP 的工具抽象设计：

• Property支持三种类型：kPropertyTypeBoolean、kPropertyTypeInteger、kPropertyTypeString；整数类型可声明min_value/max_value范围，可选参数可带默认值；所有参数在序列化为 JSON Schema 时会输出type、default、minimum、maximum等字段。
• McpTool由名称、自然语言描述、参数列表和回调函数组成，可标记为user_only（仅对用户可见、对 AI 不可见的工具，序列化时附带annotations.audience: ["user"]）。
• ReturnValue是一个std::variant<bool, int, std::string, cJSON*, ImageContent*>，即工具返回值可以是布尔、整数、字符串、JSON 对象甚至 Base64 编码的图片内容（如摄像头拍照结果）。

内置工具清单

McpServer::AddCommonTools（main/mcp_server.cc）注册所有设备通用的工具，且刻意将常用工具放在工具列表最前面，以利用大模型侧的prompt cache特性加速响应：

• self.get_device_status：获取设备实时状态（音频、屏幕、电池、网络等），既是回答“现在音量多少”这类问题的手段，也是执行设备控制前的第一步；
• self.audio_speaker.set_volume：设置音量，参数volume为 0–100 的整数；
• self.screen.set_brightness：设置屏幕亮度（0–100）；
• self.screen.set_theme：切换亮色 / 暗色主题（LVGL 显示场景）；
• self.camera.take_photo：拍照并返回图片解释（摄像头硬件场景）。

McpServer::AddUserOnlyTools（main/mcp_server.cc）注册面向设备用户（而非大模型）的系统级工具：

• self.get_system_info：获取系统信息；
• self.reboot：重启系统；
• self.upgrade_firmware：从指定 URL 下载并安装固件后自动重启；
• self.screen.get_info/self.screen.snapshot/self.screen.preview_image：屏幕信息查询、截屏上传（multipart/form-data）、屏幕预览图片；
• self.assets.set_download_url：设置自定义 Assets 的下载地址。

从板卡注册自定义工具：以 ESP-Hi 机器狗为例

除了内置工具，各板卡可以在自己的构造函数中调用InitializeTools注册专属工具（定制板卡教程见 docs/custom-board_zh.md）。以 main/boards/espressif/esp-hi/esp_hi.cc 为例，ESP-Hi 机器狗注册了：

void InitializeTools() { auto& mcp_server = McpServer::GetInstance(); // 基础动作控制：forward / backward / turn_left / turn_right / stop mcp_server.AddTool("self.dog.basic_control", "机器人的基础动作。...", PropertyList({ Property("action", kPropertyTypeString) }), this -> ReturnValue { const std::string& action = properties["action"].value<std::string>(); if (action == "forward") { servo_dog_ctrl_send(DOG_STATE_FORWARD, NULL); } else if (action == "backward") { // ... } return true; }); // 灯光控制：开关与 RGB 颜色 mcp_server.AddTool("self.light.set_rgb", "设置RGB颜色", PropertyList({ Property("r", kPropertyTypeInteger, 0, 255), Property("g", kPropertyTypeInteger, 0, 255), Property("b", kPropertyTypeInteger, 0, 255) }), this -> ReturnValue { SetLedColor(properties["r"].value<int>(), properties["g"].value<int>(), properties["b"].value<int>()); return true; }); }

AddTool的签名要点（详见 docs/mcp-usage_zh.md）：

• name：工具唯一标识，建议使用 “模块.功能” 的层次化命名（如self.dog.forward）；
• description：自然语言描述，帮助大模型理解工具用途与触发条件；
• properties：参数列表，可为空；支持布尔、整数、字符串，可声明范围和默认值；
• callback：收到调用请求时的实际执行逻辑，返回值可为 bool / int / string。

后台与设备端的典型 MCP 交互流程

README 所指的“后台”即云服务器（MCP 客户端），ESP32 设备是 MCP 服务器。完整交互时序如下（协议细节见 docs/mcp-protocol_zh.md）：

1. 连接建立与能力通告：设备启动并通过 WebSocket / MQTT 连接后台后，发送基础协议hello消息，features中声明"mcp": true；
2. initialize：后台发起 MCP 会话初始化，设备回以protocolVersion、serverInfo；若后台具备视觉能力，可在params.capabilities.vision中携带图片处理 URL 与 token（对应源码ParseCapabilities将相机解释地址写入摄像头）；
3. tools/list：后台获取设备工具列表（含inputSchema与可选nextCursor分页）；
4. tools/call：后台调用工具，设备执行后在主线程回调并返回结果。

调用示例：

// 后台 → 设备：查询工具列表 { "jsonrpc": "2.0", "method": "tools/list", "params": { "cursor": "" }, "id": 1 }

// 后台 → 设备：设置音量 { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "self.audio_speaker.set_volume", "arguments": { "volume": 50 } }, "id": 2 }

// 设备 → 后台：调用成功响应 { "jsonrpc": "2.0", "id": 2, "result": { "content": [ { "type": "text", "text": "true" } ], "isError": false } }

若工具不存在或参数非法，设备会返回error（例如"Unknown tool: self.non_existent_tool"，对应 JSON-RPC 错误码 -32601）。

硬件支持：从面包板到 138 个板卡目录

项目针对不同的硬件玩法提供了两条路线：

面包板手工制作实践

对于想从零动手的开发者，项目提供《小智 AI 聊天机器人百科全书》飞书文档教程，并给出面包板效果图：

基于面包板手工搭建的小智 AI 聊天机器人参考效果

板卡生态

仓库中已有138 个板卡目录、171 个固件发布变体（README 仅展示部分），覆盖乐鑫 ESP32-S3-BOX-3、M5Stack CoreS3 / AtomS3R + Echo Base、立创·实战派、微雪电子、LILYGO、虾哥 Mini C3、无名科技星智、SenseCAP Watcher、ESP-HI 机器狗等主流硬件（对应目录见 main/boards）。各板卡目录下包含config.json、config.h与板卡实现文件，例如 ESP-HI 位于 main/boards/espressif/esp-hi，ESP32-S3-BOX-3 位于 main/boards/espressif/esp32-s3-box-3。开发新板卡时建议先阅读 docs/custom-board_zh.md。

固件烧录与开发环境搭建

免开发环境烧录（新手推荐）

新手第一次操作建议直接使用免开发环境烧录的固件，无需搭建任何开发环境。固件默认接入 xiaozhi.me 官方服务器，个人用户注册账号即可免费使用 Qwen 实时模型。配套的《新手烧录固件教程》可参考项目 README 中的指引。

本地开发环境

• 推荐 IDE：Cursor 或 VSCode；
• 安装ESP-IDF 插件，首选 ESP-IDF v6.0.2，建议使用 v6.0 及以上稳定版；ESP-IDF v5.5.2 仅保留用于旧版硬件兼容；
• 操作系统：Linux 优于 Windows（编译速度快，且免去驱动问题）；
• 代码风格：项目遵循 Google C++ 代码风格，提交代码时需符合规范（参见 docs/code_style_zh.md）。

开发者文档索引

README 整理了完整的文档体系，均位于仓库docs/目录下：

• ESP-IDF 6.0 迁移文档：SDK 兼容性、组件变更、旧版硬件支持和板卡验证状态；
• 自定义开发板指南：为小智 AI 创建自定义开发板；
• MCP 协议物联网控制用法说明：通过 MCP 协议控制物联网设备；
• MCP 协议交互流程：设备端 MCP 协议的实现方式；
• MQTT + UDP 混合通信协议文档；
• WebSocket 通信协议文档。

大模型配置与后台控制台

如果你已经拥有一台接入官方服务器的小智设备，可以登录 xiaozhi.me 控制台完成大模型配置（Qwen / DeepSeek 等）。README 同时提供了后台操作视频教程（旧版界面）供参考。

此外，README 列举了多种可选的第三方服务器实现与客户端生态：

• 自部署服务器：Python 版 xiaozhi-esp32-server、Java 版 xiaozhi-esp32-server-java、Golang 版 xiaozhi-server-go 与 xiaozhi-esp32-server-golang；
• 第三方客户端：Python 客户端 py-xiaozhi、Android 客户端 xiaozhi-android-client、Linux 客户端 xiaozhi-linux、蓝牙芯片固件 xiaozhi-sf32、移远 QuecPython 固件 solution-xiaozhiAI。

关于项目与开源许可

本项目由虾哥开源，以MIT 许可证发布，允许任何人免费使用、修改或用于商业用途（见 LICENSE）。项目希望通过 ESP32 硬件实践，帮助开发者了解 AI 硬件开发，把当下飞速发展的大语言模型真正应用到实际硬件设备中。如有建议可提交 Issues 或加入社区群组交流。

小结

xiaozhi-esp32 的独特之处在于：它把“语音交互”与“MCP 工具调用”深度绑定——设备不仅是麦克风与扬声器，更是一个可被大模型发现和驱动的“工具服务器”。无论是开箱即用的官方固件、覆盖 138 个板卡的硬件生态，还是可自由扩展的AddTool工具注册机制，都为把大模型能力落地到物理世界提供了一条低门槛、高可玩性的路径。下一篇深入实践时，建议从 docs/mcp-protocol_zh.md 的协议细节与 main/mcp_server.cc 的内置工具实现入手，尝试为你的板卡注册第一个自定义 MCP 工具。

【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32