使用说明

项目简介

mcp2mqtt 项目旨在连接物联网设备和 AI 大模型，作为一个 Model Context Protocol (MCP) 服务器，它使用 MQTT 协议与硬件设备通信，并允许 AI 客户端通过 MCP 协议调用工具来控制这些设备。通过 mcp2mqtt，用户可以使用支持 MCP 协议的客户端（如 Claude Desktop, Cline）以自然语言指令控制连接到 MQTT 网络的硬件设备。

主要功能点

MQTT 设备桥接: 将 MQTT 协议的物联网设备接入 MCP 生态。
自然语言控制硬件: 通过 MCP 客户端发送自然语言指令，转换为 MQTT 命令控制硬件设备。
工具集成: 将 MQTT 设备操作封装为 MCP 工具，方便 LLM 客户端调用。
灵活配置: 通过 YAML 配置文件管理 MQTT 连接参数和可用的硬件控制命令。
支持多种 MCP 客户端: 兼容实现了 MCP 协议的客户端，如 Claude Desktop, Continue, Cline 等。
快速安装: 提供一键安装脚本，简化部署过程。

安装步骤

根据操作系统选择安装方式：项目提供了 Windows、macOS 和 Ubuntu/Raspberry Pi 的安装脚本，请根据你的操作系统，参考仓库 README.md 文件中的【快速开始】-> 【1. 安装】部分，下载并运行对应的安装脚本。例如，在 macOS 上，可以执行以下命令：
```
curl -O https://raw.githubusercontent.com/mcp2everything/mcp2mqtt/main/install_macos.py
python3 install_macos.py
```
安装脚本会自动检查环境、安装依赖、创建配置文件并配置 Claude 桌面版 (如果已安装)。
手动安装 (可选)：如果自动安装失败或需要自定义安装，可以参考 README.md 文件中【从源码快速开始】部分，手动安装 uv 工具和 mcp2mqtt 项目。

服务器配置

MCP 服务器配置是在 MCP 客户端中进行的，用于告知客户端如何启动和连接 mcp2mqtt 服务器。以下是通用的 JSON 格式配置信息，你需要将其添加到你的 MCP 客户端（例如 Claude Desktop 或 Cline）的配置文件中。

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

配置参数说明：

'"mcpServers"': 固定字段，表示 MCP 服务器配置信息。
'"mcp2mqtt"': 服务器名称，可以自定义，但在客户端配置中需要保持唯一。
'"command"': 启动 MCP 服务器的命令。这里 '"uvx"' 是一个用于执行 Python 程序的工具，确保你的环境中已安装 uv 工具。如果你的环境中 'uvx' 不可用，可以尝试使用 'uv run' 或直接使用 'python' 命令，并根据实际安装路径调整 'args' 参数。
'"args"': 传递给 'command' 的参数。'["mcp2mqtt"]' 表示运行 mcp2mqtt 服务器程序，这会调用 'mcp2mqtt' 包的入口点。

注意：

请根据你的 MCP 客户端的具体配置方法，将上述 JSON 配置添加到客户端的配置文件中。
修改 MCP 客户端配置后，通常需要重启客户端软件才能使配置生效。

基本使用方法

配置 'config.yaml' 文件: 安装完成后，根据提示修改 'config.yaml' 配置文件，主要是配置 MQTT Broker 的连接信息（地址、端口、用户名、密码等）以及串口设备 (如果需要串口通信)。配置文件默认位于用户主目录下的 '.mcp2mqtt' 文件夹中。
启动 mcp2mqtt 服务器: 打开终端，激活 mcp2mqtt 的虚拟环境（如果使用源码安装），然后运行启动命令：
```
uv run mcp2mqtt
```
或者，如果需要指定配置文件，可以使用 '--config' 参数，例如：
```
uv run mcp2mqtt --config Pico
```
配置 MCP 客户端: 将上面提供的 JSON 配置添加到你的 MCP 客户端（如 Claude Desktop, Cline）的配置文件中，并确保客户端已正确连接到 mcp2mqtt 服务器。
使用自然语言指令控制硬件: 在 MCP 客户端中，你可以使用自然语言指令，例如 “把 PWM 调到最大”, “打开 LED” 等，客户端会将这些指令通过 MCP 协议发送给 mcp2mqtt 服务器，服务器解析指令并转换为 MQTT 消息发送给相应的硬件设备，从而实现自然语言控制硬件的功能。
测试: 可以使用项目 'tests' 目录下的 'responder.py' 模拟 MQTT 设备进行测试，或者连接真实的 MQTT 设备进行功能验证。

关键词