About MQTT
MQTT is an MCP server that connects to MQTT 5.0 brokers using the standard wire protocol. It lets clients publish messages, manage buffered subscriptions, inspect connection state, and approximate topic discovery through retained messages.
Key features
- 01Publish messages with MQTT 5 properties
- 02Start and manage topic subscriptions
- 03Buffer and retrieve subscription messages
- 04Check broker connection status
- 05Approximate topic discovery via retained messages
Use cases
- 01Publish telemetry to an MQTT broker
- 02Read messages matching topic filters
- 03Inspect retained messages to discover topics
MCP support
The server exposes MQTT broker connection, publishing, subscription, message retrieval, and topic discovery tools to MCP clients. It uses the standard MQTT 5.0 protocol and requires broker connection settings.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
uvx mqtt5-mcp-serverMQTT_HOSTBroker hostname or IPMQTT_PORTBroker port, default 1883 (or 8883 for TLS)MQTT_USERNAMEBroker usernameMQTT_PASSWORDSecretBroker passwordMQTT_USE_TLStrue/false, default falseLocal servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.
Details
From the project READMEMQTT 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
| Tool | Description |
|---|---|
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 var | Required | Description |
|---|---|---|
MQTT_HOST | Yes | Broker hostname or IP. |
MQTT_PORT | No | Default 1883 (or 8883 for TLS — set explicitly). |
MQTT_USERNAME / MQTT_PASSWORD | No | Broker credentials. |
MQTT_CLIENT_ID | No | Defaults to a broker-assigned ID. |
MQTT_KEEPALIVE | No | Seconds, default 60. |
MQTT_CONNECT_TIMEOUT | No | Seconds to wait for the initial connect, default 10. |
MQTT_TRANSPORT | No | tcp (default) or websockets. |
MQTT_WS_PATH | No | Path for the websocket transport, default /mqtt. |
MQTT_USE_TLS | No | true/false, default false. |
MQTT_TLS_CA_CERTS | No | Path to a CA bundle. Omit to use the system trust store. |
MQTT_TLS_CLIENT_CERT / MQTT_TLS_CLIENT_KEY | No | For mutual TLS. |
MQTT_TLS_INSECURE | No | Skip hostname verification — for self-signed test certs only. |
MQTT_WILL_TOPIC / MQTT_WILL_PAYLOAD / MQTT_WILL_QOS / MQTT_WILL_RETAIN | No | Last Will and Testament, set once at connect time. |
Running locally
uv sync
export MQTT_HOST=localhost
export MQTT_PORT=1883
export MQTT_USERNAME=mqtt
export MQTT_PASSWORD=mqtt
uv 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.
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 automatically
docker 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.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.