MCP 服务器

mcp2mqtt

This server bridges the Model Context Protocol (MCP) to the MQTT protocol, allowing LLMs to interact with IoT devices and hardware systems through configurable message topics. It enables users to map natural language prompts to specific MQTT commands for controlling devices like Raspberry Pi fans or PWM controllers.

README

一、配置说明

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后缀
            ]
        }
    }
}