Skip to content
Back to search

mqtt-mcp

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/majinju--mqtt-mcp/badge.svg)](/listings/majinju--mqtt-mcp)

HTML

<a href="/listings/majinju--mqtt-mcp"><img src="/api/listings/majinju--mqtt-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

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

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

npm i -g mqtt-mcp-server

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 221 lines
  1. # mqtt-mcp
  2. 通用 MQTT 连接器 MCP Server。连接参数在使用时通过工具配置并持久化到本地;配置一次后,日常只需按业务消息协议调用 `mqtt_send` 发送消息,无需再关心 Broker 地址、主题拼接和报文格式。
  3. ## 特性
  4. - **运行时配置连接**:通过 `mqtt_configure` 传入 host/port/账号/TLS 等参数,支持多命名连接,配置落盘复用。
  5. - **业务协议模板**:用 `mqtt_template_save` 定义主题与消息体模板,支持 `{{变量}}` 插值、嵌套路径、默认值、内置变量与缺失变量校验。
  6. - **一行发送**:`mqtt_send` 只需模板名 + 业务变量,连接未建立时自动连接。
  7. - **完整发布/订阅**:原始 `publish` / `subscribe` / `unsubscribe` / `messages`(带内存缓冲与主题过滤)。
  8. - **可靠性**:自动重连、连接状态跟踪、原子化配置写入、优雅退出。
  9. ## 安装
  10. 无需安装,直接在 MCP 客户端用 `npx` 启动:
  11. ```json
  12. {
  13. "mcpServers": {
  14. "mqtt": {
  15. "command": "npx",
  16. "args": ["-y", "mqtt-mcp-server"]
  17. }
  18. }
  19. }
  20. ```
  21. 需要 Node.js >= 18。也可以全局安装后直接运行 `mqtt-mcp-server`:
  22. ```bash
  23. npm i -g mqtt-mcp-server
  24. ```
  25. ## 从源码构建
  26. 需要 Node.js >= 18。
  27. ```bash
  28. npm install
  29. npm run build
  30. npm test # 端到端冒烟测试(内置本地 Broker)
  31. ```
  32. ## 接入 MCP 客户端
  33. 服务通过 stdio 通信。以 Claude Desktop / WorkBuddy 等客户端的 MCP 配置为例:
  34. ```json
  35. {
  36. "mcpServers": {
  37. "mqtt": {
  38. "command": "node",
  39. "args": ["F:/workspace/mqtt-mcp/dist/index.js"]
  40. }
  41. }
  42. }
  43. ```
  44. 可选参数:
  45. - `--config-dir <目录>`:指定配置文件目录;也可用环境变量 `MQTT_MCP_CONFIG_DIR`。默认 `~/.mqtt-mcp/config.json`。
  46. - 所有日志写入 stderr,不会污染 MCP 协议流。
  47. ## 上架 WorkBuddy Connector 市场
  48. 仓库中的 `connector/` 目录已按 [WorkBuddy 开放平台 Connector 规范](https://open.workbuddy.cn/docs/connector) 准备好上架包:
  49. ```
  50. connector/
  51. ├── connector-meta.json
  52. ├── mcp.json
  53. ├── icon.svg
  54. └── skills/
  55. └── mqtt-connector-skill/
  56. └── SKILL.md
  57. ```
  58. 上架前需要先发布 npm 包(连接器通过 `npx -y mqtt-mcp-server` 拉起服务):
  59. ```bash
  60. npm login
  61. npm publish
  62. ```
  63. 然后将 `connector/` 目录打包提交至 WorkBuddy 开放平台审核,审核通过后即可发布到 Connector 市场。开放平台地址:<https://open.workbuddy.cn>。
  64. ## 官方 MCP Registry
  65. 仓库根目录的 `server.json` 用于发布到 [官方 MCP Registry](https://registry.modelcontextprotocol.io/),便于各类 MCP 市场与客户端同步:
  66. ```bash
  67. mcp-publisher validate
  68. mcp-publisher login github
  69. mcp-publisher publish
  70. ```
  71. 发布前需要先完成上面的 `npm publish`,因为 Registry 只托管元数据,不托管包本体。
  72. ## 快速开始(推荐流程)
  73. 以下示例为 MCP 工具调用(参数为 `arguments`)。
  74. ### 1. 配置连接(只需一次)
  75. ```json
  76. {
  77. "name": "factory",
  78. "host": "broker.example.com",
  79. "port": 1883,
  80. "protocol": "mqtt",
  81. "username": "user",
  82. "password": "pass",
  83. "clientId": "my-app-001"
  84. }
  85. ```
  86. 调用工具 `mqtt_configure`。配置会保存到本地,下次启动无需重复配置。
  87. > TLS:使用 `mqtts`/`wss`,并通过 `ca` / `cert` / `key` 传入 PEM 内容(不是文件路径);自签证书可设 `rejectUnauthorized: false`。
  88. ### 2. 定义业务消息协议(每种消息一次)
  89. ```json
  90. {
  91. "name": "device_control",
  92. "connection": "factory",
  93. "description": "设备控制指令",
  94. "topic": "factory/{{deviceId}}/control",
  95. "payload": {
  96. "msgId": "{{ $uuid }}",
  97. "cmd": "{{ command }}",
  98. "params": "{{ params }}",
  99. "timeout": "{{ timeout | 30 }}",
  100. "ts": "{{ $now }}"
  101. },
  102. "qos": 1
  103. }
  104. ```
  105. 调用 `mqtt_template_save`。`mqtt_templates` 可查看所有模板及其需要的变量。
  106. ### 3. 日常发送(只用这一步)
  107. ```json
  108. {
  109. "template": "device_control",
  110. "variables": {
  111. "deviceId": "D001",
  112. "command": "reboot",
  113. "params": { "delay": 5 }
  114. }
  115. }
  116. ```
  117. 调用 `mqtt_send`。它会渲染出主题 `factory/D001/control` 与消息体并发布;若连接尚未建立会自动连接。需要临时切换 Broker 可加 `connection` 覆盖。
  118. ## 占位符语法
  119. | 写法 | 说明 |
  120. | --- | --- |
  121. | `{{deviceId}}` | 取变量 `deviceId`,缺失时默认报错 |
  122. | `{{device.info.name}}` | 点号访问嵌套对象 |
  123. | `{{timeout \| 30}}` | 带默认值,变量缺失时使用(支持字符串/数字/布尔/对象字面量) |
  124. | `{{ $now }}` | 当前 ISO 时间 |
  125. | `{{ $timestamp }}` | 当前毫秒时间戳 |
  126. | `{{ $date }}` | 当前日期 `YYYY-MM-DD` |
  127. | `{{ $uuid }}` | UUID v4 |
  128. 规则:
  129. - 当**整个字符串**是单个占位符时保留原始类型。例如 `"params": "{{ params }}"` 且 `params` 传对象,则消息体中就是对象而不是字符串。
  130. - 混合在文本中时按字符串拼接,如 `"device-{{deviceId}}-v2"`。
  131. - 模板默认 `strict: true`,任何必需变量缺失会报错并拒绝发送;设为 `false` 则缺失变量替换为空字符串。
  132. ## 工具一览(13 个)
  133. | 工具 | 作用 |
  134. | --- | --- |
  135. | `mqtt_configure` | 新增/更新命名连接配置并持久化 |
  136. | `mqtt_connections` | 查看连接配置与实时状态(不含密码) |
  137. | `mqtt_connect` | 建立命名连接 |
  138. | `mqtt_disconnect` | 断开连接(保留配置) |
  139. | `mqtt_remove_connection` | 删除连接配置 |
  140. | `mqtt_publish` | 发布原始消息 |
  141. | `mqtt_subscribe` | 订阅主题(支持 `+` / `#`) |
  142. | `mqtt_unsubscribe` | 取消订阅 |
  143. | `mqtt_messages` | 读取接收消息(可按连接/主题/时间过滤,支持清空) |
  144. | `mqtt_template_save` | 定义/更新业务协议模板 |
  145. | `mqtt_templates` | 查看全部模板及所需变量 |
  146. | `mqtt_send` | **按业务协议发送消息(核心)** |
  147. | `mqtt_template_remove` | 删除业务模板 |
  148. ## 接收消息示例
  149. ```json
  150. // 订阅
  151. { "connection": "factory", "topic": "factory/+/status", "qos": 0 }
  152. // 读取(工具 mqtt_messages)
  153. { "connection": "factory", "topicFilter": "factory/+/status", "limit": 20, "clear": true }
  154. ```
  155. 返回的消息包含 `topic`、`payload`(字符串)、`json`(解析成功时的对象)、`qos`、`retain`、`receivedAt`。缓冲上限为每连接 500 条,超出后丢弃最旧的。
  156. ## 安全说明
  157. - 连接密码以明文保存在 `~/.mqtt-mcp/config.json`,请控制该文件权限,不要提交到版本库。
  158. - 如需多环境隔离,用 `--config-dir` 指定不同目录。
  159. ## 项目结构
  160. ```
  161. src/
  162. index.ts MCP 服务器入口(stdio)
  163. tools.ts 13 个工具的 schema 与处理逻辑
  164. mqtt-manager.ts 连接管理、发布订阅、消息缓冲
  165. template.ts 业务协议模板引擎
  166. config-store.ts 配置持久化(原子写入)
  167. types.ts 数据类型
  168. test/smoke.mjs 端到端冒烟测试
  169. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.