
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 端到端冒烟测试
mqtt-mcp-servernpm install mqtt-mcp-server