Repository avatar
Other Tools
v1.0.0
active

mqtt-mcp

io.github.majinju/mqtt-mcp

通用 MQTT 连接器:运行时配置 Broker,支持发布/订阅与业务消息协议模板

Documentation

mqtt-mcp

通用 MQTT 连接器 MCP Server。连接参数在使用时通过工具配置并持久化到本地;配置一次后,日常只需按业务消息协议调用 mqtt_send 发送消息,无需再关心 Broker 地址、主题拼接和报文格式。

特性

  • 运行时配置连接:通过 mqtt_configure 传入 host/port/账号/TLS 等参数,支持多命名连接,配置落盘复用。
  • 业务协议模板:用 mqtt_template_save 定义主题与消息体模板,支持 {{变量}} 插值、嵌套路径、默认值、内置变量与缺失变量校验。
  • 一行发送:mqtt_send 只需模板名 + 业务变量,连接未建立时自动连接。
  • 完整发布/订阅:原始 publish / subscribe / unsubscribe / messages(带内存缓冲与主题过滤)。
  • 可靠性:自动重连、连接状态跟踪、原子化配置写入、优雅退出。

安装

无需安装,直接在 MCP 客户端用 npx 启动:

{
  "mcpServers": {
    "mqtt": {
      "command": "npx",
      "args": ["-y", "mqtt-mcp-server"]
    }
  }
}

需要 Node.js >= 18。也可以全局安装后直接运行 mqtt-mcp-server:

npm i -g mqtt-mcp-server

从源码构建

需要 Node.js >= 18。

npm install
npm run build
npm test          # 端到端冒烟测试(内置本地 Broker)

接入 MCP 客户端

服务通过 stdio 通信。以 Claude Desktop / WorkBuddy 等客户端的 MCP 配置为例:

{
  "mcpServers": {
    "mqtt": {
      "command": "node",
      "args": ["F:/workspace/mqtt-mcp/dist/index.js"]
    }
  }
}

可选参数:

  • --config-dir <目录>:指定配置文件目录;也可用环境变量 MQTT_MCP_CONFIG_DIR。默认 ~/.mqtt-mcp/config.json。
  • 所有日志写入 stderr,不会污染 MCP 协议流。

上架 WorkBuddy Connector 市场

仓库中的 connector/ 目录已按 WorkBuddy 开放平台 Connector 规范 准备好上架包:

connector/
├── connector-meta.json
├── mcp.json
├── icon.svg
└── skills/
    └── mqtt-connector-skill/
        └── SKILL.md

上架前需要先发布 npm 包(连接器通过 npx -y mqtt-mcp-server 拉起服务):

npm login
npm publish

然后将 connector/ 目录打包提交至 WorkBuddy 开放平台审核,审核通过后即可发布到 Connector 市场。开放平台地址:https://open.workbuddy.cn。

官方 MCP Registry

仓库根目录的 server.json 用于发布到 官方 MCP Registry,便于各类 MCP 市场与客户端同步:

mcp-publisher validate
mcp-publisher login github
mcp-publisher publish

发布前需要先完成上面的 npm publish,因为 Registry 只托管元数据,不托管包本体。

快速开始(推荐流程)

以下示例为 MCP 工具调用(参数为 arguments)。

1. 配置连接(只需一次)

{
  "name": "factory",
  "host": "broker.example.com",
  "port": 1883,
  "protocol": "mqtt",
  "username": "user",
  "password": "pass",
  "clientId": "my-app-001"
}

调用工具 mqtt_configure。配置会保存到本地,下次启动无需重复配置。

TLS:使用 mqtts/wss,并通过 ca / cert / key 传入 PEM 内容(不是文件路径);自签证书可设 rejectUnauthorized: false。

2. 定义业务消息协议(每种消息一次)

{
  "name": "device_control",
  "connection": "factory",
  "description": "设备控制指令",
  "topic": "factory/{{deviceId}}/control",
  "payload": {
    "msgId": "{{ $uuid }}",
    "cmd": "{{ command }}",
    "params": "{{ params }}",
    "timeout": "{{ timeout | 30 }}",
    "ts": "{{ $now }}"
  },
  "qos": 1
}

调用 mqtt_template_save。mqtt_templates 可查看所有模板及其需要的变量。

3. 日常发送(只用这一步)

{
  "template": "device_control",
  "variables": {
    "deviceId": "D001",
    "command": "reboot",
    "params": { "delay": 5 }
  }
}

调用 mqtt_send。它会渲染出主题 factory/D001/control 与消息体并发布;若连接尚未建立会自动连接。需要临时切换 Broker 可加 connection 覆盖。

占位符语法

写法说明
{{deviceId}}取变量 deviceId,缺失时默认报错
{{device.info.name}}点号访问嵌套对象
{{timeout | 30}}带默认值,变量缺失时使用(支持字符串/数字/布尔/对象字面量)
{{ $now }}当前 ISO 时间
{{ $timestamp }}当前毫秒时间戳
{{ $date }}当前日期 YYYY-MM-DD
{{ $uuid }}UUID v4

规则:

  • 当整个字符串是单个占位符时保留原始类型。例如 "params": "{{ params }}" 且 params 传对象,则消息体中就是对象而不是字符串。
  • 混合在文本中时按字符串拼接,如 "device-{{deviceId}}-v2"。
  • 模板默认 strict: true,任何必需变量缺失会报错并拒绝发送;设为 false 则缺失变量替换为空字符串。

工具一览(13 个)

工具作用
mqtt_configure新增/更新命名连接配置并持久化
mqtt_connections查看连接配置与实时状态(不含密码)
mqtt_connect建立命名连接
mqtt_disconnect断开连接(保留配置)
mqtt_remove_connection删除连接配置
mqtt_publish发布原始消息
mqtt_subscribe订阅主题(支持 + / #)
mqtt_unsubscribe取消订阅
mqtt_messages读取接收消息(可按连接/主题/时间过滤,支持清空)
mqtt_template_save定义/更新业务协议模板
mqtt_templates查看全部模板及所需变量
mqtt_send按业务协议发送消息(核心)
mqtt_template_remove删除业务模板

接收消息示例

// 订阅
{ "connection": "factory", "topic": "factory/+/status", "qos": 0 }

// 读取(工具 mqtt_messages)
{ "connection": "factory", "topicFilter": "factory/+/status", "limit": 20, "clear": true }

返回的消息包含 topic、payload(字符串)、json(解析成功时的对象)、qos、retain、receivedAt。缓冲上限为每连接 500 条,超出后丢弃最旧的。

安全说明

  • 连接密码以明文保存在 ~/.mqtt-mcp/config.json,请控制该文件权限,不要提交到版本库。
  • 如需多环境隔离,用 --config-dir 指定不同目录。

项目结构

src/
  index.ts           MCP 服务器入口(stdio)
  tools.ts           13 个工具的 schema 与处理逻辑
  mqtt-manager.ts    连接管理、发布订阅、消息缓冲
  template.ts        业务协议模板引擎
  config-store.ts    配置持久化(原子写入)
  types.ts           数据类型
test/smoke.mjs       端到端冒烟测试
NPM
mqtt-mcp-server
Install Command
npm install mqtt-mcp-server
Runtime: npx