mcp2mqtt
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Integrations
Offers dedicated installation support for macOS systems through installation scripts
Core integration allowing communication with IoT devices using MQTT protocol for publishing/subscribing to commands and responses
Supports installation and compatibility with Raspberry Pi devices through dedicated installation scripts
mcp2mqtt: 连接物理世界与AI大模型的桥梁
English | 简体中文
系统架构
工作流程
项目愿景
mcp2mqtt 是一个将物联网设备接入AI大模型的项目,它通过 Model Context Protocol (MCP) 和 MQTT 协议将物理世界与 AI 大模型无缝连接。最终实现:
- 用自然语言控制你的硬件设备
- AI 实时响应并调整物理参数
- 让你的设备具备理解和执行复杂指令的能力
- 通过MQTT协议实现设备间的互联互通
主要特性
- 智能MQTT通信
- 支持MQTT协议的发布/订阅模式
- 支持多种MQTT服务器(如Mosquitto、EMQ X等)
- 支持QoS服务质量保证
- 支持主题过滤和消息路由
- 实时状态监控和错误处理
- MCP 协议集成
- 完整支持 Model Context Protocol
- 支持资源管理和工具调用
- 灵活的提示词系统
- 通过MQTT实现命令的发布与响应
配置说明
MQTT配置
命令配置
MQTT 命令和响应
命令格式
命令使用简单的文本格式:
- PWM 控制:
- 命令:
PWM {值}
- 示例:
PWM 100
(最大值)PWM 0
(关闭)PWM 50
(50%)
- 响应:
CMD PWM {值} OK
- 命令:
- LED 控制:
- 命令:
LED {状态}
- 示例:
LED on
(打开)LED off
(关闭)
- 响应:
CMD LED {状态} OK
- 命令:
- 设备信息:
- 命令:
INFO
- 响应:
CMD INFO {设备信息}
- 命令:
错误响应
如果发生错误,响应格式将为:
ERROR: {错误信息}
支持的客户端
mcp2mqtt 支持所有实现了 MCP 协议的客户端,以及支持MQTT协议的物联网设备:
客户端类型 | 特性支持 | 说明 |
---|---|---|
Claude Desktop | 完整支持 | 推荐使用,支持所有 MCP 功能 |
Continue | 完整支持 | 优秀的开发工具集成 |
Cline | 资源+工具 | 支持多种 AI 提供商 |
MQTT设备 | 发布/订阅 | 支持所有MQTT协议的物联网设备 |
快速开始
1. 安装
Windows用户
下载 install.py
macOS用户
Ubuntu/Raspberry Pi用户
安装脚本会自动完成以下操作:
- 检查系统环境
- 安装必要的依赖
- 创建默认配置文件
- 配置Claude桌面版(如果已安装)
手动分步安装依赖
主要依赖uv工具,所以当python和uv以及Claude或Cline安装好后就可以了。
基本配置
在你的 MCP 客户端(如 Claude Desktop 或 Cline)配置文件中添加以下内容: 注意:如果使用的自动安装那么会自动配置Calude Desktop无需此步。 使用默认配置文件:
注意:修改配置后需要重启Cline或者Claude客户端软件
配置说明
配置文件位置
复制配置文件(config.yaml
)可以放在位置:
用户主目录(推荐个人使用)
- 适用场景:个人配置
- 需要创建
.mcp2mqtt
目录:Copy
指定配置文件: 比如指定加载Pico配置文件:Pico_config.yaml
为了能使用多个mqtt,我们可以新增多个mcp2mqtt的服务 指定不同的配置文件名即可。 如果要接入多个设备,如有要连接第二个设备: 指定加载Pico2配置文件:Pico2_config.yaml
硬件连接
- 将你的设备通过网络连接到mqtt服务器
- 也可以用tests目录下的responder.py来模拟设备
运行测试
启动设备模拟器
项目在 tests
目录中包含了一个设备模拟器。它可以模拟一个硬件设备,能够:
- 响应 PWM 控制命令
- 提供设备信息
- 控制 LED 状态
启动模拟器:
你应该能看到模拟器正在运行并已连接到 MQTT 服务器的输出信息。
启动客户端Claude 桌面版或Cline
从源码快速开始
- 从源码安装
MCP客户端配置
在使用支持MCP协议的客户端(如Claude Desktop或Cline)时,需要在客户端的配置文件中添加以下内容: 直接自动安装的配置方式 源码开发的配置方式
使用默认演示参数:
指定参数文件名
2. 用户主目录(推荐个人使用)
- 适用场景:个人配置
- 需要创建
.mcp2mqtt
目录:Copy
3. 系统级配置(适合多用户环境)
- 适用场景:多用户共享配置
- 创建目录并设置权限:Copy
程序会按照上述顺序查找配置文件,使用找到的第一个有效配置文件。根据你的需求选择合适的位置:
- 开发测试:使用当前目录
- 个人使用:建议使用用户主目录(推荐)
- 多用户环境:使用系统级配置(ProgramData或/etc)
- 运行服务器: