# mcp2mqtt: 连接物理世界与AI大模型的桥梁 [English](README_EN.md) | 简体中文

通过自然语言控制硬件，开启物联网新纪元

## 系统架构

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服务器端口 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" # 接收控制命令的主题 ``` ### 命令配置 ```yaml 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 命令和响应 ### 命令格式命令使用简单的文本格式： 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](https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install.py) ```bash python install.py ``` #### macOS用户 ```bash # 下载安装脚本 curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install_macos.py # 运行安装脚本 python3 install_macos.py ``` #### Ubuntu/Raspberry Pi用户 ```bash # 下载安装脚本 curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install_ubuntu.py # 运行安装脚本 python3 install_ubuntu.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配置文件：Pico_config.yaml ```json { "mcpServers": { "mcp2mqtt": { "command": "uvx", "args": [ "mcp2mqtt", "--config", "Pico" //指定配置文件名，不需要添加_config.yaml后缀 ] } } } ``` 为了能使用多个mqtt，我们可以新增多个mcp2mqtt的服务指定不同的配置文件名即可。如果要接入多个设备，如有要连接第二个设备：指定加载Pico2配置文件：Pico2_config.yaml ```json { "mcpServers": { "mcp2mqtt2": { "command": "uvx", "args": [ "mcp2mqtt", "--config", "Pico2" //指定配置文件名，不需要添加_config.yaml后缀 ] } } } ``` ### 硬件连接 1. 将你的设备通过网络连接到mqtt服务器 2. 也可以用tests目录下的responder.py来模拟设备 ## 运行测试 ### 启动设备模拟器项目在 `tests` 目录中包含了一个设备模拟器。它可以模拟一个硬件设备，能够： - 响应 PWM 控制命令 - 提供设备信息 - 控制 LED 状态启动模拟器： ```bash python tests/responder.py ``` 你应该能看到模拟器正在运行并已连接到 MQTT 服务器的输出信息。 ### 启动客户端Claude 桌面版或Cline

Example in Cline

### 从源码快速开始 1. 从源码安装 ```bash # 通过源码安装： 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）时，需要在客户端的配置文件中添加以下内容：直接自动安装的配置方式源码开发的配置方式 #### 使用默认演示参数： ```json { "mcpServers": { "mcp2mqtt": { "command": "uv", "args": [ "--directory", "你的实际路径/mcp2mqtt", // 例如: "C:/Users/Administrator/Documents/develop/my-mcp-server/mcp2mqtt" "run", "mcp2mqtt" ] } } } ``` #### 指定参数文件名 ```json { "mcpServers": { "mcp2mqtt": { "command": "uv", "args": [ "--directory", "你的实际路径/mcp2mqtt", // 例如: "C:/Users/Administrator/Documents/develop/my-mcp-server/mcp2mqtt" "run", "mcp2mqtt", "--config", // 可选参数，指定配置文件名 "Pico" // 可选参数，指定配置文件名，不需要添加_config.yaml后缀 ] } } } ```

Example in Cline

### 配置文件位置配置文件（`config.yaml`）可以放在不同位置，程序会按以下顺序查找： #### 1. 当前工作目录（适合开发测试） - 路径：`./config.yaml` - 示例：如果你在 `C:\Projects` 运行程序，它会查找 `C:\Projects\config.yaml` - 适用场景：开发和测试 - 不需要特殊权限 #### 2. 用户主目录（推荐个人使用） ```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 ``` #### 3. 系统级配置（适合多用户环境） ```bash # Windows系统（需要管理员权限） C:\ProgramData\mcp2mqtt\config.yaml # macOS/Linux系统（需要root权限） /etc/mcp2mqtt/config.yaml ``` - 适用场景：多用户共享配置 - 创建目录并设置权限： ```bash # 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） 3. 运行服务器： ```bash # 确保已激活虚拟环境 .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 ``` ## 文档 - [安装指南](./docs/zh/installation.md) - [API文档](./docs/zh/api.md) - [配置说明](./docs/zh/configuration.md)