How do I use mcp2mqtt?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp2mqtt set the PWM frequency to maximum" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp2mqtt by BLACKHKER

一、配置说明

1.1 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"  # 接收控制命令的主题

1.2 命令配置

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响应主题

二、快速开始

2.1 基础安装

MCP客户端测试用的安装在VSCode上的Cline插件实现，后续默认已安装

uv(测试版本0.10.7)
ffmpeg(测试版本2026-03-03)
MCP客户端(Cline或Claude Desktop)

2.2 基本配置

修改配置后需要重启Cline或者Claude客户端软件，我是安装在VSCode上，重启VS即可

修改MCP客户端的配置：

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

三、运行测试

3.1 从源码快速开始

# 拉取仓库
git clone https://github.com/BLACKHKER/mcp2mqtt.git
cd mcp2mqtt

# 创建虚拟环境
uv venv .venv

# 激活虚拟环境
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

# 安装开发依赖
uv pip install --editable .

# 运行服务器（使用默认配置config.yaml）
uv run src/mcp2mqtt/server.py
或
uv run mcp2mqtt

# 从指定配置运行服务器（例如指定配置Pi_config.yaml）
uv run src/mcp2mqtt/server.py --config Pi
或
uv run mcp2mqtt --config Pi

3.2 MCP客户端配置

在使用支持MCP协议的客户端（如Claude Desktop或Cline）时，需要修改客户端的配置文件：

使用默认演示参数：

{
  "mcpServers": {
    "mcp2mqtt": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "D:/PyCharmWorkspace/mcp2mqtt/src/mcp2mqtt",
        "run",
        "mcp2mqtt"
      ]
    }
  }
}

指定参数文件名

{
    "mcpServers": {
        "mcp2mqtt": {
            "command": "uv",
            "args": [
                "--directory",
                "D:/PyCharmWorkspace/mcp2mqtt/src/mcp2mqtt",
                "run",
                "mcp2mqtt",
                "--config", // 可选参数，指定配置文件名
                "Pico"  // 可选参数，指定配置文件名，不需要添加_config.yaml后缀
            ]
        }
    }
}

3.3 启动设备模拟器

项目在 tests 目录中包含了一个设备模拟器response.py。它可以模拟一个硬件设备，能够：

提供树莓派信息
控制树莓派风扇

mcp2mqtt