站点图标 高效码农

mcp2mqtt实战：零代码用自然语言控制硬件，一句话搞定！

高效码农

用自然语言就能控制硬件：mcp2mqtt 入门与实践

“把灯调到最亮”“风扇开到 50%”——一句话，让 AI 替你按下开关

开篇：为什么需要 mcp2mqtt？

想像一下，你回到家，只说一句“客厅灯调到 45%”，灯光便自动变暗；或者你在办公室，用键盘敲下“打开空调”，空调立刻启动。过去，这类“自然语言控制 IoT 设备”的方案要么需要复杂的语音集成，要么得写一堆脚本。mcp2mqtt 把这件事简化为三步：

  1. 把设备插在串口上
  2. 写一份 20 行左右的 YAML 说明
  3. 打开 Claude Desktop、Cline 或任意支持 MCP 协议的客户端，直接聊天即可

本文不聊噱头，只讲原理、配置、踩坑与真实场景。

技术速览：mcp2mqtt 到底是什么？

术语 一句话解释
MCP 协议 Claude 团队公开的一套“AI 调用外部工具”的通用协议
MQTT 轻量级物联网消息总线，手机推送、智能家居都在用
mcp2mqtt 把 MCP 协议翻译成 MQTT 命令，再把设备串口数据回传给 AI 的“翻译官”

一句话总结：
mcp2mqtt = MCP 协议适配器 + MQTT 客户端 + 串口助手。

系统架构：数据如何在三跳之间流动

  1. AI 客户端（Claude Desktop、Cline、Continue）
    发出自然语言 → 按 MCP 格式打包 → 交给 mcp2mqtt

  2. mcp2mqtt
    拆包 → 查 YAML 配置 → 生成串口指令 → 发向设备
    收到设备回应 → 打包成 MQTT → 回传给 AI

  3. 设备端
    串口收到 “PWM 75\n” → 执行 → 回 “OK” → 一切结束

准备工作：我需要哪些软硬件？

类别 最低需求 推荐清单
电脑 Win10 / macOS 12 / Ubuntu 22 带 USB-A 或 USB-C
Python 3.11+ 3.12
线材 任意 USB-转-串口线 CH340、CP2102、FT232 均可
单片机 支持串口 115200 baud ESP32、STM32、Arduino Nano 等
客户端 Claude Desktop、Cline、Continue Claude Desktop（体验最佳）

五分钟安装：各平台一步到位

Windows

curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install.py
python install.py

macOS

curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install_macos.py
python3 install_macos.py

Ubuntu / 树莓派

curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install_ubuntu.py
python3 install_ubuntu.py

脚本会：

  • 检查 Python 版本
  • 安装 pyserial、mcp 等依赖
  • 生成默认 config.yaml
  • 把 Claude Desktop 配置好（若已安装）

配置文件放在哪？三种场景三种路径

使用场景 路径示例 特点
开发调试 项目根目录 ./config.yaml 改完立即生效，无需权限
个人电脑 ~/.mcp2mqtt/config.yaml 重装系统不丢配置
多人共享服务器 /etc/mcp2mqtt/config.yaml root 权限，统一配置

创建目录示例：

# macOS / Linux
mkdir -p ~/.mcp2mqtt
# Windows CMD
mkdir "%USERPROFILE%\.mcp2mqtt"

串口 & MQTT：一份最小可用配置

1. 串口参数

serial:
  port: auto-detect   # 也可写 COM11、/dev/ttyUSB0
  baud_rate: 115200

2. MQTT 参数

mqtt:
  broker: localhost
  port: 1883
  client_id: mcp2mqtt_client
  username: mqtt_user
  password: mqtt_password
  topics:
    command:    mcp/command
    response:   mcp/response

3. 命令模板

commands:
  set_pwm:
    command: "PWM {frequency}\n"
    need_parse: false
    prompts:
      - "Set PWM to {value}%"
      - "把 PWM 调到 {value}%"

注意：{frequency}、{value} 占位符可自动被 AI 填上具体数值。

让 Claude Desktop 识别 mcp2mqtt

打开 Claude Desktop 的配置文件（路径取决于系统）：

{
  "mcpServers": {
    "mcp2mqtt": {
      "command": "uvx",
      "args": ["mcp2mqtt"]
    }
  }
}

本地源码调试时，用绝对路径：

{
  "mcpServers": {
    "mcp2mqtt": {
      "command": "uv",
      "args": [
        "--directory", "C:/Users/you/projects/mcp2mqtt",
        "run", "mcp2mqtt"
      ]
    }
  }
}

实战对话：四句话完成硬件控制

场景：ESP32 控制 LED 亮度，串口协议为 PWM <0-100>。

你对 Claude 说 Claude 背后做了什么
“把灯调到 50%” 匹配 prompts → 发 MQTT → 串口写 PWM 50\n
“再亮一点” 解析上下文 → 计算 75% → 写 PWM 75\n
“关灯” 映射到 0% → 写 PWM 0\n
“现在亮度多少？” 调用 get_pwm 命令 → 回显结果

常见疑问（FAQ）

Q1：为什么我的串口一直连不上？

  • 确认波特率 115200
  • 在 Windows 用设备管理器看 COM 号；在 Linux 用 ls /dev/tty*
  • 关闭占用串口的其他软件（Arduino IDE、串口助手）

Q2：Claude 报错 “mcp2mqtt not found”？

  • 检查 uvx mcp2mqtt 能否在终端直接运行
  • 若源码调试，请用绝对路径且使用 / 或 \\

Q3：MQTT 连不上本地 Mosquitto？

  • 确认 Mosquitto 服务已启动：systemctl status mosquitto
  • 检查 config.yaml 的 broker 是不是 localhost
  • 防火墙放行 1883 端口

Q4：可以一次控制多个设备吗？

  • 可以。每个设备写一组 YAML 命令，topic 用 mcp/device1、mcp/device2 区分
  • 在 prompts 里加设备名即可，如“把客厅的灯调到 30%”

进阶：带解析的温控示例

需求：单片机返回 OK TEMP=25.5，让 AI 直接告诉你温度。

commands:
  get_temperature:
    command: "GET_TEMP\n"
    need_parse: true
    prompts:
      - "现在温度多少？"

返回示例：

{
  "status": "success",
  "result": {
    "raw": "OK TEMP=25.5"
  }
}

Claude 会自动提取 25.5 并回答“现在温度 25.5 °C”。

源码安装：想改功能就这么做

git clone https://github.com/mcp2everything/mcp2mqtt.git
cd mcp2mqtt

uv venv .venv
source .venv/bin/activate  # Windows 用 .venv\Scripts\activate
uv pip install --editable .

# 运行
uv run src/mcp2mqtt/server.py

改完代码后，uv run 会自动重载，无需重复安装。

测试与持续集成

项目使用 pytest：

uv pytest tests/

开发者提 PR 前，请保证测试通过并补充用例。

许可与致谢

  • 源码：MIT 许可证
  • 感谢 Claude 团队公开 MCP 协议
  • 感谢 pySerial 让串口通信不再痛苦

下一步可以做什么？

  • 把家里的空调、风扇、加湿器全部用 YAML 描述一张“自然语言控制表”
  • 用 Node-RED 把 mcp2mqtt 的 MQTT 消息与 HomeKit 打通
  • 在群晖 NAS 上跑 Mosquitto，实现 24×7 离家远程控制

如果你已经用 mcp2mqtt 做出了有趣的项目，欢迎在 GitHub 分享你的 YAML 模板，让更多人一句话就能控制世界。

退出移动版