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
| 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.
1 maintainer
Metadata
1 maintainer
Release files for mqtt5-mcp-server 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| mqtt5_mcp_server-0.1.0.tar.gz | 96.4 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mqtt5_mcp_server-0.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 105.2 kB
Release files / mqtt5_mcp_server-0.1.0.tar.gz
| Download URL | mqtt5_mcp_server-0.1.0.tar.gz |
|---|---|
| Size | 96.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d2e328c32c4be5eee12d45381d6b0aef0e9cb8c8aa888abe4f0b01fe94bcf3d2
|
|
BLAKE2b-256 checksum How to use checksums |
87f0340c38809c9cc8dd1a21c7e5ad0d6c796bddeadcc4f49b06c9e32fa373c0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / mqtt5_mcp_server-0.1.0-py3-none-any.whl
| Download URL | mqtt5_mcp_server-0.1.0-py3-none-any.whl |
|---|---|
| Size | 8.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0c111d57a7f88801bf596d2f4789694ceb0e71fb4f10f68dd0db4e590b802a6f
|
|
BLAKE2b-256 checksum How to use checksums |
d74251b06a0da35641bd5ce38a01cc842495e655f596acf6f4e59f3cbbdcee6a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for mqtt5-mcp-server 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
