Skip to main content
Glama

mqtt-mcp

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

特性

  • 运行时配置连接:通过 mqtt_configure 传入 host/port/账号/TLS 等参数,支持多命名连接,配置落盘复用。

  • 业务协议模板:用 mqtt_template_save 定义主题与消息体模板,支持 {{变量}} 插值、嵌套路径、默认值、内置变量与缺失变量校验。

  • 一行发送:mqtt_send 只需模板名 + 业务变量,连接未建立时自动连接。

  • 完整发布/订阅:原始 publish / subscribe / unsubscribe / messages(带内存缓冲与主题过滤)。

  • 可靠性:自动重连、连接状态跟踪、原子化配置写入、优雅退出。

Related MCP server: Coreflux MQTT MCP Server

安装

无需安装,直接在 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       端到端冒烟测试

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables LLM agents to interact with MQTT brokers through publish, subscribe, and query operations. Provides fine-grained topic permissions with wildcard support for secure IoT device communication and sensor data access.
      13 PyPI
      2
      BSD 3-Clause
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Connects to a Coreflux MQTT broker and provides tools for managing Coreflux commands (models, actions, rules, routes) and executing MQTT operations through natural language interactions with AI assistants.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects AI assistants to MQTT brokers for smart home automation and IoT device control, enabling topic discovery, sensor reading, command sending, and event monitoring.
      2
      MIT