River AI实战：用n8n+MCP打造语音控制ESP32的智能体

一个大学生的毕业设计，把语音助手、n8n工作流、MCP协议和ESP32硬件串联到一起，实现了语音读取传感器数据并控制6路电器。这个名为River AI的项目，提供了一个值得拆解的低代码AI Agent落地范例。

项目概览：语音驱动的物联网智能体

据YouTube上来自楠榜大学（Universitas Lampung）信息技术专业学生Nabila Rahmadiani的演示，River AI是一个可以被语音指挥的AI Agent。它通过语音转文字（Speech to Text）接收指令，能够读取由ESP32采集的温度、湿度和距离数据，还能开关由6个LED灯代表的6种电器——灯、电视、冰箱、空调、洗衣机和收音机。

整个系统的核心在于MCP（Model Context Protocol）协议的应用。它把n8n变成一个工具提供方，让AI Agent可以按需调用这些工具，再通过HTTP请求与运行在Linux虚拟机上的Python后端通信，最终驱动真实硬件。这种架构把"大模型推理"与"硬件执行"清晰地解耦开来。

MCP（Model Context Protocol）是由Anthropic于2024年底提出并开源的标准协议，旨在解决AI大模型与外部工具、数据源之间的集成碎片化问题。其核心思想是将"工具提供方"（MCP Server）与"工具调用方"（MCP Client/Agent）解耦：Server负责声明自己能做什么、暴露哪些接口；Client（通常是AI Agent）按需发现并调用这些工具，无需为每个集成单独编写适配代码。这种设计类似于USB-C的统一接口理念——不同来源的工具只要遵循同一协议，Agent就能直接使用。n8n从1.x版本起原生支持MCP节点，使得非开发者也能通过可视化界面搭建符合MCP规范的工具服务，这正是River AI能以低代码方式实现硬件控制的技术基础。

后端架构：server.py作为数据交汇点

项目的服务端运行在一台Linux虚拟机上，启动了两样东西：Docker里的n8n，以及一个用Flask写的小服务server.py。

Reaver AI文件夹里有三个关键文件。index.html是6种设备的仪表盘，卡片会根据状态亮起或熄灭；reaver.service让服务以后台方式运行，可以用systemctl命令启停；而真正的"数据中枢"是server.py。

server.py承担三项任务：保存ESP32最后一次上传的传感器数值、保存6个设备的开关状态、接收开/关指令。作者解释了为什么必须有这个中间层——n8n、ESP32和仪表盘三者共享同一份数据，server.py就是它们汇合的地方。这个设计思路对任何需要多端数据同步的IoT项目都有参考价值：与其让各端互相直连，不如设一个统一的状态存储。

从仪表盘可以看到所有设备初始状态都是关闭的，而传感器API端显示着来自ESP32的温度、湿度和距离数据，ESP状态为online。

Flask是Python生态中极为轻量的Web框架，适合快速搭建小型HTTP API服务。在River AI这类IoT项目里，它承担的角色是"状态服务器"而非完整后端——只需维护几个全局变量（传感器最新值、设备开关状态），并通过GET/POST端点对外暴露读写接口即可。这种"内存状态+HTTP接口"的极简模式在原型项目中非常常见：ESP32周期性POST上传数据，n8n通过GET读取，仪表盘轮询刷新，三者完全通过HTTP解耦，无需任何直连。代价是服务重启后状态丢失，如需持久化则要引入SQLite或Redis等存储层，但对毕设演示场景已完全够用。

n8n双工作流：MCP的服务端与客户端分离

作者在n8n中设计了两个独立的工作流，这正是对MCP"双端"特性的直接映射。

MCP服务端工作流

第一个工作流作为MCP Server，使用了三个节点。核心是MCP Server Trigger节点，它让n8n充当MCP服务器，开放一个地址，挂在它下面的工具都能被Agent调用。

工具一是"读取传感器"，用HTTP Request节点以GET方式访问server.py的传感器API，取回最新的温湿度和距离。工具二是"控制设备"，用POST方式访问控制API，参数包含设备名和动作（开或关）。一个关键细节是：设备和动作的具体值由AI通过from AI表达式自己填入，依据的正是用户说出的那句话。

AI Agent聊天工作流

第二个工作流处理对话。入口是一个Webhook节点，接收来自网页的语音转文字结果，并开启了CORS让浏览器可以调用。

整个工作流的大脑是AI Agent节点。作者在系统提示词里设定了角色人格——名叫River AI、由Nabila创建、回答要简短且不带Markdown（因为要被语音朗读）、而且必须先调用工具再声称自己完成了操作。这最后一条约束很重要，它避免了大模型"幻觉式"地假装执行了实际没做的动作。

聊天模型选用Google Gemini，并加了Memory节点，以网页传来的Session ID为键记住对话上下文。再通过MCP Client节点连接到前面的MCP Server工作流，让所有工具对Agent可用。最后用Respond to Webhook节点把回复以JSON（reply字段）返回给网页。

部署清单：从发布工作流到烧录ESP32

工作流做好后还有几步必做的准备工作，作者梳理得相当清楚。

第一步是发布两个工作流，因为生产环境的Webhook和MCP地址只有在发布后才生效，任何改动都要重新发布。第二步是在网页的HTML里把Webhook常量填成虚拟机的IP和生产URL，让前端知道该把文字发往哪里。

第三步用Arduino IDE把程序烧进ESP32，这里要注意引脚配置、WiFi名称和服务器地址都要正确，而且ESP32必须和虚拟机处于同一网络才能连通。第四步在Windows PowerShell里用python -m http.server 8000启动本地web服务器，再通过localhost在Chrome中打开页面——因为Chrome只在localhost或HTTPS下才允许使用麦克风。这个浏览器麦克风权限的限制，是很多Web语音项目容易踩的坑。

硬件方面，ESP32接了DHT11温湿度传感器、HC-SR04超声波测距传感器和6个LED。ESP32每2秒向服务器发送一次传感器数据，服务器的回复里带着设备状态，用来点亮或熄灭对应的LED。

ESP32是乐鑫（Espressif）推出的低成本微控制器，集成了Wi-Fi和蓝牙，是目前最主流的IoT开发板之一。DHT11是常见的数字温湿度传感器，测温精度±2°C、湿度精度±5%RH，价格极低但足够教学演示使用。HC-SR04是超声波测距模块，通过发射40kHz声波并计算回波时间来测量距离，量程约2cm至4m。Arduino IDE支持通过ESP32官方板卡包对其进行编程，烧录前需在工具菜单选择正确的开发板型号和串口，并在代码中硬编码Wi-Fi SSID/密码及服务器IP——这也意味着更换网络环境时需要重新烧录固件，是此类原型项目在生产化时需要改进的点（可改用配网模式或从配置服务器拉取参数）。

实机演示：语音问答与设备控制

演示环节验证了整条链路。

当作者问"房间温度多少"，River回答"31.2摄氏度"；问湿度得到"65.8%"；问最近物体距离得到"6.9厘米"——传感器读取功能全部打通。接着的设备控制同样顺利："打开灯"后第一个LED亮起，"打开所有设备"后6个LED全亮，"关闭所有设备"后全部熄灭。前端界面还做了拟人化设计，River被塑造成一个会随交互出现的魔法师角色。

这个项目的参考价值

抛开它作为学生毕设的身份，River AI示范了一套相当完整的"AI Agent + 低代码 + 物联网"组合拳。它用MCP把工具调用标准化，用n8n降低了编排门槛，用Flask中间层解决了多端数据一致性，再用系统提示词约束大模型的行为边界。对于想入门AI Agent硬件控制的开发者来说，这是一个麻雀虽小、五脏俱全的参考样本。真正的工程难点往往不在模型本身，而在于把语音、协议、硬件和权限这些环节逐一打通。