mcp2everything/mcp2mqtt

English | 简体中文
通过自然语言控制硬件，开启物联网新纪元
## 系统架构
mcp2mqtt 系统架构图
## 工作流程
mcp2mqtt 工作流程图
## 项目愿景
mcp2mqtt 是一个将物联网设备接入AI大模型的项目，它通过 Model Context Protocol (MCP) 和 MQTT 协议将物理世界与 AI 大模型无缝连接。最终实现：
用自然语言控制你的硬件设备
AI 实时响应并调整物理参数
让你的设备具备理解和执行复杂指令的能力
通过MQTT协议实现设备间的互联互通
## 主要特性
智能MQTT通信
支持MQTT协议的发布/订阅模式
支持多种MQTT服务器（如Mosquitto、EMQ X等）
支持QoS服务质量保证
支持主题过滤和消息路由
实时状态监控和错误处理
MCP 协议集成
完整支持 Model Context Protocol
支持资源管理和工具调用
灵活的提示词系统
通过MQTT实现命令的发布与响应
## 配置说明
### MQTT配置
yaml
mqtt:
broker: "localhost" # MQTT服务器地址
port: 1883 # MQTT服务器端口
clientid: "mcp2mqttclient" # MQTT客户端ID
username: "mqttuser" # MQTT用户名
password: "mqttpassword" # MQTT密码
keepalive: 60 # 保持连接时间
topics:
command:
publish: "mcp/command" # 发送命令的主题
subscribe: "mcp/response" # 接收响应的主题
status:
publish: "mcp/status" # 发送状态的主题
subscribe: "mcp/control" # 接收控制命令的主题
### 命令配置
yaml
commands:
setpwm:
command: "CMDPWM {frequency}"
needparse: false
datatype: "ascii"
prompts:
"把PWM调到最大"
"把PWM调到最小"
mqtttopic: "mcp/pwm" # MQTT发布主题
responsetopic: "mcp/pwm/response" # MQTT响应主题
## MQTT 命令和响应
### 命令格式
命令使用简单的文本格式：
1. PWM 控制：
命令：PWM {值}
示例：
PWM 100（最大值）
PWM 0（关闭）
PWM 50（50%）
响应：CMD PWM {值} OK
2. LED 控制：
命令：LED {状态}
示例：
LED on（打开）
LED off（关闭）
响应：CMD LED {状态} OK
3. 设备信息：
命令：INFO
响应：CMD INFO {设备信息}
### 错误响应
如果发生错误，响应格式将为：
ERROR: {错误信息}
## 支持的客户端
mcp2mqtt 支持所有实现了 MCP 协议的客户端，以及支持MQTT协议的物联网设备：
| 客户端类型 | 特性支持 | 说明 |
| Claude Desktop | 完整支持 | 推荐使用，支持所有 MCP 功能 |
| Continue | 完整支持 | 优秀的开发工具集成 |
| Cline | 资源+工具 | 支持多种 AI 提供商 |
| MQTT设备 | 发布/订阅 | 支持所有MQTT协议的物联网设备 |
## 快速开始
### 1. 安装
#### Windows用户
下载 install.py
bash
python install.py
#### macOS用户
bash
# 下载安装脚本
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/installmacos.py
# 运行安装脚本
python3 installmacos.py
#### Ubuntu/Raspberry Pi用户
bash
# 下载安装脚本
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/installubuntu.py
# 运行安装脚本
python3 installubuntu.py
安装脚本会自动完成以下操作：
检查系统环境
安装必要的依赖
创建默认配置文件
配置Claude桌面版（如果已安装）
### 手动分步安装依赖
bash
windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
MacOS
curl -LsSf https://astral.sh/uv/install.sh | sh
主要依赖uv工具，所以当python和uv以及Claude或Cline安装好后就可以了。
### 基本配置
在你的 MCP 客户端（如 Claude Desktop 或 Cline）配置文件中添加以下内容：
注意：如果使用的自动安装那么会自动配置Calude Desktop无需此步。
使用默认配置文件：
json
"mcpServers": {
"mcp2mqtt": {
"command": "uvx",
"args": [
"mcp2mqtt"
> 注意：修改配置后需要重启Cline或者Claude客户端软件
## 配置说明
### 配置文件位置
复制配置文件（config.yaml）可以放在位置：
用户主目录（推荐个人使用）
bash
# Windows系统
C:\Users\用户名\.mcp2mqtt\config.yaml
# macOS系统
/Users/用户名/.mcp2mqtt/config.yaml
# Linux系统
/home/用户名/.mcp2mqtt/config.yaml
适用场景：个人配置
需要创建 .mcp2mqtt 目录：
bash
# Windows系统（在命令提示符中）
mkdir "%USERPROFILE%\.mcp2mqtt"
# macOS/Linux系统
mkdir -p ~/.mcp2mqtt
指定配置文件：
比如指定加载Pico配置文件：Picoconfig.yaml
json
"mcpServers": {
"mcp2mqtt": {
"command": "uvx",
"args": [
"mcp2mqtt",
"--config",
"Pico" //指定配置文件名，不需要添加config.yaml后缀
为了能使用多个mqtt，我们可以新增多个mcp2mqtt的服务 指定不同的配置文件名即可。
如果要接入多个设备，如有要连接第二个设备：
指定加载Pico2配置文件：Pico2config.yaml
json
"mcpServers": {
"mcp2mqtt2": {
"command": "uvx",
"args": [
"mcp2mqtt",
"--config",
"Pico2" //指定配置文件名，不需要添加config.yaml后缀
### 硬件连接
1. 将你的设备通过网络连接到mqtt服务器
2. 也可以用tests目录下的responder.py来模拟设备
## 运行测试
### 启动设备模拟器
项目在 tests 目录中包含了一个设备模拟器。它可以模拟一个硬件设备，能够：
响应 PWM 控制命令