Back to search
mqtt-mcp
MCP serverGitHub
通用 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
Markdown
[](/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
- # mqtt-mcp
- 通用 MQTT 连接器 MCP Server。连接参数在使用时通过工具配置并持久化到本地;配置一次后,日常只需按业务消息协议调用 `mqtt_send` 发送消息,无需再关心 Broker 地址、主题拼接和报文格式。
- ## 特性
- - **运行时配置连接**:通过 `mqtt_configure` 传入 host/port/账号/TLS 等参数,支持多命名连接,配置落盘复用。
- - **业务协议模板**:用 `mqtt_template_save` 定义主题与消息体模板,支持 `{{变量}}` 插值、嵌套路径、默认值、内置变量与缺失变量校验。
- - **一行发送**:`mqtt_send` 只需模板名 + 业务变量,连接未建立时自动连接。
- - **完整发布/订阅**:原始 `publish` / `subscribe` / `unsubscribe` / `messages`(带内存缓冲与主题过滤)。
- - **可靠性**:自动重连、连接状态跟踪、原子化配置写入、优雅退出。
- ## 安装
- 无需安装,直接在 MCP 客户端用 `npx` 启动:
- ```json
- {
- "mcpServers": {
- "mqtt": {
- "command": "npx",
- "args": ["-y", "mqtt-mcp-server"]
- }
- }
- }
- ```
- 需要 Node.js >= 18。也可以全局安装后直接运行 `mqtt-mcp-server`:
- ```bash
- npm i -g mqtt-mcp-server
- ```
- ## 从源码构建
- 需要 Node.js >= 18。
- ```bash
- npm install
- npm run build
- npm test # 端到端冒烟测试(内置本地 Broker)
- ```
- ## 接入 MCP 客户端
- 服务通过 stdio 通信。以 Claude Desktop / WorkBuddy 等客户端的 MCP 配置为例:
- ```json
- {
- "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 规范](https://open.workbuddy.cn/docs/connector) 准备好上架包:
- ```
- connector/
- ├── connector-meta.json
- ├── mcp.json
- ├── icon.svg
- └── skills/
- └── mqtt-connector-skill/
- └── SKILL.md
- ```
- 上架前需要先发布 npm 包(连接器通过 `npx -y mqtt-mcp-server` 拉起服务):
- ```bash
- npm login
- npm publish
- ```
- 然后将 `connector/` 目录打包提交至 WorkBuddy 开放平台审核,审核通过后即可发布到 Connector 市场。开放平台地址:<https://open.workbuddy.cn>。
- ## 官方 MCP Registry
- 仓库根目录的 `server.json` 用于发布到 [官方 MCP Registry](https://registry.modelcontextprotocol.io/),便于各类 MCP 市场与客户端同步:
- ```bash
- mcp-publisher validate
- mcp-publisher login github
- mcp-publisher publish
- ```
- 发布前需要先完成上面的 `npm publish`,因为 Registry 只托管元数据,不托管包本体。
- ## 快速开始(推荐流程)
- 以下示例为 MCP 工具调用(参数为 `arguments`)。
- ### 1. 配置连接(只需一次)
- ```json
- {
- "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. 定义业务消息协议(每种消息一次)
- ```json
- {
- "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. 日常发送(只用这一步)
- ```json
- {
- "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` | 删除业务模板 |
- ## 接收消息示例
- ```json
- // 订阅
- { "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 端到端冒烟测试
- ```
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.