MQTT

io.github.nagarjunrPublished by GitHub account nagarjunrv0.1.0Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyCloud & InfrastructureDeveloper Tools

Overview

AI-generated overview

Local MCP server that connects an assistant to an MQTT 5.0 broker to publish messages, run subscription sessions and discover topics.

What you can do
Check the connector's broker connection state and list active subscription sessions, then stop them when done. Publish messages to a topic, with MQTT 5 properties and optional waiting for broker acknowledgement at QoS 1/2. Start subscriptions on topic filters with wildcards, returning a session ID, and drain buffered messages with a bounded wait. Approximate topic listing by collecting retained messages matching a filter.
When to use it
Useful when an assistant needs to work with an IoT or messaging broker: sending commands or test payloads to devices, watching a topic stream over several tool calls, or surveying which topics carry retained messages. Works with any standard MQTT 5.0 broker rather than a specific vendor's admin API.
Requirements
Runs locally as a Python package via uvx (stdio). Requires MQTT_HOST; optional MQTT_PORT (default 1883, 8883 for TLS), MQTT_USERNAME and MQTT_PASSWORD, MQTT_USE_TLS, plus optional client ID, keepalive, transport, TLS certificate and Last Will settings. Network access to the broker is needed.
Before you install
Publishing writes to the broker and can reach real devices or downstream consumers; retained messages persist for later subscribers. Subscriptions buffer incoming messages in the background until stopped. The broker password is supplied through MQTT_PASSWORD, and mutual TLS options take client certificate and key paths. MQTT_TLS_INSECURE skips hostname verification and is meant only for self-signed test certificates.

Installation

In SourceWeft

  1. Open MQTT in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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.

Source: mqtt/README.md at commit eb4532a

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts