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 分