mqtt-mcp-server
by majinju
README.md
# 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 端到端冒烟测试
```
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues