MQTT

io.github.nagarjunr由 GitHub 账号 nagarjunr 发布v0.1.0更新于 Oct 24, 2026

MCP server for MQTT 5.0 brokers (publish, subscribe, topic discovery).

已验证STDIO仅桌面云端与基础设施开发者工具

概览

AI 生成的概览

本地 MCP 服务器，让助手连接 MQTT 5.0 代理，发布消息、运行订阅会话并发现主题。

可以做什么
查看连接器与代理的连接状态，列出并停止活动的订阅会话。向指定主题发布消息，支持 MQTT 5 属性，并可在 QoS 1/2 下等待代理确认。按支持通配符的主题过滤器启动订阅并返回会话 ID，再分批取出缓冲的消息，可短暂等待新消息。通过收集匹配过滤器的保留消息来近似列出主题。
适用场景
适合需要操作物联网或消息代理的场景：向设备发送命令或测试负载、跨多次工具调用持续观察某个主题的消息流，或了解哪些主题带有保留消息。适用于任何标准 MQTT 5.0 代理，而不依赖特定厂商的管理接口。
运行要求
以 Python 包形式通过 uvx 在本地运行（stdio）。需要 MQTT_HOST；可选 MQTT_PORT（默认 1883，TLS 用 8883）、MQTT_USERNAME 与 MQTT_PASSWORD、MQTT_USE_TLS，以及可选的客户端 ID、keepalive、传输方式、TLS 证书和遗嘱消息设置。需要能访问该代理的网络。
安装前请注意
发布消息会写入代理，可能触达真实设备或下游消费者；保留消息会持续存在供后续订阅者读取。订阅会在后台缓冲收到的消息，直到被停止。代理密码通过 MQTT_PASSWORD 提供，双向 TLS 选项需要客户端证书和私钥路径。MQTT_TLS_INSECURE 会跳过主机名校验，仅应用于自签名测试证书。

安装

在 SourceWeft 中

  1. 打开 控制台中的 MQTT，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

MQTT MCP Server

A Model Context Protocol (MCP) server for MQTT — the standard IoT publish/subscribe messaging protocol. Works against any MQTT broker (Eclipse Mosquitto, EMQX, HiveMQ, AWS IoT Core, Azure IoT Hub's MQTT endpoint, etc): only the standard MQTT 5.0 wire protocol is used, no broker-specific admin APIs.

Built with FastMCP and paho-mqtt.

Tools

ToolDescription
get_connection_status()Report this connector's broker connection state.
publish_message(topic, payload, qos, retain, ...)Publish a message. Supports MQTT5 properties (content type, message expiry, response topic, correlation data, user properties) and optionally blocks until the broker acknowledges delivery (QoS 1/2).
start_subscription(topic_filter, qos, ...)Start receiving messages matching a topic filter (supports +/# wildcards). Returns a session_id.
get_messages(session_id, max_messages, timeout_seconds)Drain buffered messages from a subscription session; can wait briefly for one to arrive.
stop_subscription(session_id)Stop a session and unsubscribe (if no other session needs the same filter).
list_subscriptions()List all active subscription sessions.
discover_topics(topic_filter, duration_seconds, max_topics)Approximate a "list topics" operation via retained messages — MQTT has no native topic-listing operation.

Why subscriptions are session-based

MQTT is a continuous publish/subscribe stream, not a request/response API. A single MCP tool call can't "wait forever" for messages, so subscribing works in two steps: start_subscription registers interest and buffers messages in the background (one shared broker connection, dispatched in-process by topic filter), then get_messages drains that buffer on however many tool calls you want, optionally waiting a bounded amount of time for new data. Call stop_subscription when done.

Configuration

Env varRequiredDescription
MQTT_HOSTYesBroker hostname or IP.
MQTT_PORTNoDefault 1883 (or 8883 for TLS — set explicitly).
MQTT_USERNAME / MQTT_PASSWORDNoBroker credentials.
MQTT_CLIENT_IDNoDefaults to a broker-assigned ID.
MQTT_KEEPALIVENoSeconds, default 60.
MQTT_CONNECT_TIMEOUTNoSeconds to wait for the initial connect, default 10.
MQTT_TRANSPORTNotcp (default) or websockets.
MQTT_WS_PATHNoPath for the websocket transport, default /mqtt.
MQTT_USE_TLSNotrue/false, default false.
MQTT_TLS_CA_CERTSNoPath to a CA bundle. Omit to use the system trust store.
MQTT_TLS_CLIENT_CERT / MQTT_TLS_CLIENT_KEYNoFor mutual TLS.
MQTT_TLS_INSECURENoSkip hostname verification — for self-signed test certs only.
MQTT_WILL_TOPIC / MQTT_WILL_PAYLOAD / MQTT_WILL_QOS / MQTT_WILL_RETAINNoLast Will and Testament, set once at connect time.

Running locally

bash
uv syncexport MQTT_HOST=localhostexport MQTT_PORT=1883export MQTT_USERNAME=mqttexport MQTT_PASSWORD=mqttuv run mqttmcpserver.py

See mcp.json for ready-to-use client configs (stdio and Docker).

Testing against a real broker

This repo's design principles call for testing against a real instance rather than mocks. docker-compose.yml spins up Eclipse Mosquitto (2.x, MQTT5-capable) with password auth, plus a TLS listener with self-signed certs for testing the TLS/mTLS code paths.

bash
./docker/gen-test-certs.sh # one-time: generate throwaway TLS test certs (needs openssl)docker compose up -d       # start Mosquitto on localhost:1883 (plain, user: mqtt / pass: mqtt) and :8883 (TLS)uv run pytest -v           # tests/conftest.py also starts/stops the stack automaticallydocker compose down        # stop it manually if you started it yourself

License notes

docker-compose.yml and the files under docker/ configure the open-source Eclipse Mosquitto broker (EPL-2.0) for local testing only — they are not part of the MCP server itself.

来源：mqtt/README.md，提交 eb4532a

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v0.1.0最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分