Skip to main content
Glama
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       端到端冒烟测试
```