麦普转MQTT
项目介绍
技术文档摘要
mcp2mqtt: 物理世界与AI大模型之间的桥梁
<div align="center"> <img src="docs/images/logo.png" alt="mcp2mqtt Logo" width="200"/> <p>通过自然语言控制硬件，开启物联网新纪元</p> </div>系统架构
<div align="center"> <img src="docs/images/stru_chs.png" alt="系统架构图" width="800"/> <p>mcp2mqtt 系统架构图</p> </div>工作流程
<div align="center"> <img src="docs/images/workflow_chs.png" alt="工作流程图" width="800"/> <p>mcp2mqtt 工作流程图</p> </div>项目愿景
mcp2mqtt 是一个连接物联网设备与AI大模型的项目，通过Model Context Protocol (MCP) 和 MQTT协议无缝连接物理世界与AI大模型。最终实现：
- 使用自然语言控制硬件设备
- AI实时响应并调整物理参数
- 让设备理解并执行复杂指令
- 通过MQTT协议实现设备间的互联互通
主要功能
-
智能MQTT通信
- 支持MQTT协议的发布/订阅模式
- 支持多个MQTT服务器（如Mosquitto、EMQ X等）
- 支持服务质量保证（QoS）
- 支持主题过滤和消息路由
- 实时状态监控和错误处理
-
MCP协议集成
- 完全支持Model Context Protocol
- 支持资源管理和工具调用
- 灵活的提示系统
- 通过MQTT发布和响应命令
配置说明
MQTT配置
mqtt:
broker: "localhost" # MQTT服务器地址
port: 1883 # MQTT服务器端口
client_id: "mcp2mqtt_client" # MQTT客户端ID
username: "mqtt_user" # MQTT用户名
password: "mqtt_password" # MQTT密码
keepalive: 60 # 保持连接时间
topics:
command:
publish: "mcp/command" # 发送命令的主题
subscribe: "mcp/response" # 接收响应的主题
status:
publish: "mcp/status" # 发送状态的主题
subscribe: "mcp/control" # 接收控制命令的主题
命令配置
commands:
set_pwm:
command: "CMD_PWM {frequency}"
need_parse: false
data_type: "ascii"
prompts:
- "把PWM调到最大"
- "把PWM调到最小"
mqtt_topic: "mcp/pwm" # MQTT发布主题
response_topic: "mcp/pwm/response" # MQTT响应主题
MQTT命令与响应
命令格式
命令采用简单的文本格式：
-
PWM控制：
- 命令：
PWM {值} - 示例：
PWM 100(最大值)PWM 0(关闭)PWM 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协议的物联网设备 |
快速开始
安装
Windows用户
下载 install.py
python install.py
macOS用户
# 下载安装脚本
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install_macos.py
# 运行安装脚本
python3 install_macos.py
Ubuntu/Raspberry Pi用户
# 下载安装脚本
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install_ubuntu.py
# 运行安装脚本
python3 install_ubuntu.py
安装脚本将自动执行以下操作：
- 检查系统环境
- 安装必要的依赖项
- 创建默认配置文件
- 配置桌面版Claude（如果已安装）
手动分步安装依赖项
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将被自动配置，这一步是不必要的。 使用默认配置文件：
{
"mcpServers": {
"mcp2mqtt": {
"command": "uvx",
"args": [
"mcp2mqtt"
]
}
}
}
注意：修改配置后，请重启Cline或Claude客户端软件
配置说明
配置文件的位置
复制配置文件（config.yaml）可以放置在以下位置：
用户主目录（推荐用于个人使用）
# Windows系统
C:\Users\用户名\.mcp2mqtt\config.yaml
# macOS系统
/Users/用户名/.mcp2mqtt/config.yaml
# Linux系统
/home/用户名/.mcp2mqtt/config.yaml
- 适用场景：个人配置
- 需要创建
.mcp2mqtt目录# Windows系统（在命令提示符中） mkdir "%USERPROFILE%\.mcp2mqtt" # macOS/Linux系统 mkdir -p ~/.mcp2mqtt
指定配置文件： 例如，指定加载Pico配置文件：Pico_config.yaml
{
"mcpServers": {
"mcp2mqtt": {
"command": "uvx",
"args": [
"mcp2mqtt",
"--config",
"Pico" //指定配置文件名，不需要添加_config.yaml后缀
]
}
}
}
要使用多个MQTT，我们可以通过指定不同的配置文件名来添加几个mcp2mqtt服务。 如果您想连接多个设备，例如连接第二个设备： 指定加载Pico2配置文件：Pico2_config.yaml
{
"mcpServers": {
"mcp2mqtt2": {
"command": "uvx",
"args": [
"mcp2mqtt",
"--config",
"Pico2" //指定配置文件名，不需要添加_config.yaml后缀
]
}
}
}
硬件连接
- 通过网络将设备连接到MQTT服务器
- 您也可以使用tests目录中的responder.py来模拟设备
运行测试
启动设备模拟器
项目在tests目录中包含一个设备模拟器。它可以模拟一个硬件设备，并能够：
- 响应PWM控制命令
- 提供设备信息
- 控制LED状态
启动模拟器：
python tests/responder.py
您应该能看到输出信息，表明模拟器正在运行并连接到了MQTT服务器。
启动客户端Claude桌面版本或Cline
<div align="center"> <img src="docs/images/test_output.png" alt="Cline Configuration Example" width="600"/> <p>Cline示例</p> </div>从源代码快速开始
- 从源代码安装
# 通过源码安装：
git clone https://github.com/mcp2everything/mcp2mqtt.git
cd mcp2mqtt
# 创建虚拟环境
uv venv .venv
# 激活虚拟环境
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate
# 安装开发依赖
uv pip install --editable .
MCP客户端配置
当使用支持MCP协议的客户端（如Claude Desktop或Cline）时，您需要在客户端的配置文件中添加以下内容： 直接自动安装配置方法 源代码开发的配置方法
使用默认演示参数：
{
"mcpServers": {
"mcp2mqtt": {
"command": "uv",
"args": [
"--directory",
"你的实际路径/mcp2mqtt", // 例如: "C:/Users/Administrator/Documents/develop/my-mcp-server/mcp2mqtt"
"run",
"mcp2mqtt"
]
}
}
}
指定参数文件名
{
"mcpServers": {
"mcp2mqtt": {
"command": "uv",
"args": [
"--directory",
"你的实际路径/mcp2mqtt", // 例如: "C:/Users/Administrator/Documents/develop/my-mcp-server/mcp2mqtt"
"run",
"mcp2mqtt",
"--config", // 可选参数，指定配置文件名
"Pico" // 可选参数，指定配置文件名，不需要添加_config.yaml后缀
]
}
}
}
配置文件位置
配置文件（config.yaml）可以放在不同位置，程序会按以下顺序查找：
1. 当前工作目录（适合开发测试）
- 路径：
./config.yaml - 示例：如果你在
C:\Projects运行程序，它会查找C:\Projects\config.yaml - 适用场景：开发和测试
- 不需要特殊权限
2. 用户主目录（推荐用于个人使用）
# Windows系统
C:\Users\用户名\.mcp2mqtt\config.yaml
# macOS系统
/Users/用户名/.mcp2mqtt/config.yaml
# Linux系统
/home/用户名/.mcp2mqtt/config.yaml
- 适用场景：个人配置
- 需要创建
.mcp2mqtt目录# Windows系统（在命令提示符中） mkdir "%USERPROFILE%\.mcp2mqtt" # macOS/Linux系统 mkdir -p ~/.mcp2mqtt
3. 系统级配置（适用于多用户环境）
# Windows系统（需要管理员权限）
C:\ProgramData\mcp2mqtt\config.yaml
# macOS/Linux系统（需要root权限）
/etc/mcp2mqtt/config.yaml
- 适用场景：多用户共享配置
- 创建目录并设置权限：
# Windows系统（以管理员身份运行） mkdir "C:\ProgramData\mcp2mqtt" # macOS/Linux系统（以root身份运行） sudo mkdir -p /etc/mcp2mqtt sudo chown root:root /etc/mcp2mqtt sudo chmod 755 /etc/mcp2mqtt
程序将按照上述顺序搜索配置文件，并使用找到的第一个有效配置文件。根据需求选择合适的配置位置：
- 开发测试：使用当前目录
- 个人使用：推荐使用用户的主目录（推荐）
- 多用户环境：使用系统级配置（ProgramData 或 /etc）
- 运行服务器：
# 确保已激活虚拟环境
.venv\Scripts\activate
# 运行服务器（使用默认配置config.yaml 案例中用的LOOP_BACK 模拟串口，无需真实串口和串口设备）
uv run src/mcp2mqtt/server.py
或
uv run mcp2mqtt
# 运行服务器（使用指定配置Pico_config.yaml）
uv run src/mcp2mqtt/server.py --config Pico
或
uv run mcp2mqtt --config Pico