mqtt-mcp-server
Provides an MCP server for connecting to MQTT brokers, configuring named connections, publishing and subscribing to topics, buffering received messages, and sending templated business messages with variable interpolation.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 覆盖。
占位符语法
写法 | 说明 |
| 取变量 |
| 点号访问嵌套对象 |
| 带默认值,变量缺失时使用(支持字符串/数字/布尔/对象字面量) |
| 当前 ISO 时间 |
| 当前毫秒时间戳 |
| 当前日期 |
| UUID v4 |
规则:
当整个字符串是单个占位符时保留原始类型。例如
"params": "{{ params }}"且params传对象,则消息体中就是对象而不是字符串。混合在文本中时按字符串拼接,如
"device-{{deviceId}}-v2"。模板默认
strict: true,任何必需变量缺失会报错并拒绝发送;设为false则缺失变量替换为空字符串。
工具一览(13 个)
工具 | 作用 |
| 新增/更新命名连接配置并持久化 |
| 查看连接配置与实时状态(不含密码) |
| 建立命名连接 |
| 断开连接(保留配置) |
| 删除连接配置 |
| 发布原始消息 |
| 订阅主题(支持 |
| 取消订阅 |
| 读取接收消息(可按连接/主题/时间过滤,支持清空) |
| 定义/更新业务协议模板 |
| 查看全部模板及所需变量 |
| 按业务协议发送消息(核心) |
| 删除业务模板 |
接收消息示例
// 订阅
{ "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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Email inboxes, webhook URLs, mock APIs and 170+ tools for coding agents over one MCP connection.
Messaging tools for AI agents: send messages, manage chats, groups and channels.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Official WhatsApp Business API (Meta Cloud API) for your own CRM or SaaS, from WasapFlow, a Meta Tech Provider. Your AI can search the Bridge docs, list connected numbers, create Embedded Signup links so clients connect their own WhatsApp (Coexistence supported), send text and template messages, list templates, check and retry failed webhooks, see usage and open support tickets. Docs tools work without a key; account tools use the x-partner-key header.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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 PyPI2BSD 3-Clause
- AlicenseNot gradedqualityNot gradedmaintenanceConnects 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.-
- AlicenseNot gradedqualityDmaintenanceConnects AI assistants to MQTT brokers for smart home automation and IoT device control, enabling topic discovery, sensor reading, command sending, and event monitoring.2MIT
- AlicenseAqualityDmaintenanceEnables interacting with MQTT brokers to publish, subscribe, and manage connections, with a real-time web UI for visual feedback.61MIT