Allows an AI client to publish messages, subscribe to topics, and discover topics on any MQTT 5.0 broker.
Also known as nagarjunr/iot-mcp-servers, mqtt5-mcp-server
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- 96
- Latest version
- 0.1.0
- Last commit
- Oct 31, 2026
- License
- MIT
What is MQTT MCP?
MQTT allows an AI client to publish messages, subscribe to topics, and discover topics on any MQTT 5.0 broker.
Summary generated from the project's README
About MQTT MCP server
Interacting with IoT devices and messaging streams through an AI client is possible by using this MQTT server to communicate with any MQTT 5.0 broker. It works with standard brokers like Eclipse Mosquitto, EMQX, HiveMQ, AWS IoT Core, or Azure IoT Hub by utilizing the standard wire protocol rather than proprietary admin APIs. Developers set up the connection locally using environment variables for the host, port, credentials, and transport type, such as TCP or websockets.
The server provides specific tools to manage the lifecycle of messaging. You can use publish_message to send data with MQTT5 properties like content type or message expiry, and start_subscription to begin receiving data via topic filters with wildcards. Because MQTT is a continuous stream, the server uses a session-based approach where messages are buffered in the background and then retrieved using get_messages. It also includes a discover_topics tool that approximates topic listing by checking retained messages.
What you can do with it
- 1Send commands to IoT devicesAn AI can publish a specific payload to a device topic using MQTT5 properties.
- 2Monitor real-time sensor dataA developer can instruct an AI to subscribe to a topic filter and drain the buffered messages to analyze incoming data.
- 3Identify available message topicsYou can ask the AI to find out which topics are currently active on the broker by looking at retained messages.
- 4Check broker connectivityAn AI can verify if the connection to the MQTT broker is currently active or broken.
Written from the project's README. Every use case is checked against a quote from it.
How to install MQTT MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall MQTT MCP in Claude Code
$ claude mcp add --env 'MQTT_HOST=<MQTT_HOST>' --env 'MQTT_PASSWORD=<YOUR_MQTT_PASSWORD>' mqtt -- uvx mqtt5-mcp-serverInstall MQTT MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mqtt": {
"command": "uvx",
"args": [
"mqtt5-mcp-server"
],
"env": {
"MQTT_HOST": "<MQTT_HOST>",
"MQTT_PASSWORD": "<YOUR_MQTT_PASSWORD>"
}
}
}
}Install MQTT MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mqtt": {
"type": "stdio",
"command": "uvx",
"args": [
"mqtt5-mcp-server"
],
"env": {
"MQTT_HOST": "<MQTT_HOST>",
"MQTT_PASSWORD": "<YOUR_MQTT_PASSWORD>"
}
}
}
}Install MQTT MCP in VS Code CLI
$ code --add-mcp '{"name":"mqtt","type":"stdio","command":"uvx","args":["mqtt5-mcp-server"],"env":{"MQTT_HOST":"<MQTT_HOST>","MQTT_PASSWORD":"<YOUR_MQTT_PASSWORD>"}}'Install MQTT MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mqtt": {
"command": "uvx",
"args": [
"mqtt5-mcp-server"
],
"env": {
"MQTT_HOST": "<MQTT_HOST>",
"MQTT_PASSWORD": "<YOUR_MQTT_PASSWORD>"
}
}
}
}Install MQTT MCP in Codex
$ codex mcp add mqtt --env 'MQTT_HOST=<MQTT_HOST>' --env 'MQTT_PASSWORD=<YOUR_MQTT_PASSWORD>' -- uvx mqtt5-mcp-serverInstall MQTT MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mqtt] command = "uvx" args = ["mqtt5-mcp-server"] [mcp_servers.mqtt.env] MQTT_HOST = "<MQTT_HOST>" MQTT_PASSWORD = "<YOUR_MQTT_PASSWORD>"
Install MQTT MCP in Gemini CLI
$ gemini mcp add -s user -e 'MQTT_HOST=<MQTT_HOST>' -e 'MQTT_PASSWORD=<YOUR_MQTT_PASSWORD>' mqtt uvx -- mqtt5-mcp-serverInstall MQTT MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mqtt": {
"command": "uvx",
"args": [
"mqtt5-mcp-server"
],
"env": {
"MQTT_HOST": "<MQTT_HOST>",
"MQTT_PASSWORD": "<YOUR_MQTT_PASSWORD>"
}
}
}
}Configuration
MQTT_HOSTRequiredBroker hostname or IP
MQTT_PASSWORDSecretBroker password
MQTT_PORTBroker port, default 1883 (or 8883 for TLS)
MQTT_USERNAMEBroker username
MQTT_USE_TLStrue/false, default false
| Name | Description | |
|---|---|---|
| MQTT_HOST | Broker hostname or IP | Required |
| MQTT_PASSWORD | Broker password | Secret |
| MQTT_PORT | Broker port, default 1883 (or 8883 for TLS) | |
| MQTT_USERNAME | Broker username | |
| MQTT_USE_TLS | true/false, default false |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablenagarjunr/iot-mcp-servers is public and reachablegithub.com/nagarjunr/iot-mcp-servers ↗Pass
- Package names this repository as its sourcemqtt5-mcp-server names nagarjunr/iot-mcp-servers as sourcepypi.org/project/mqtt5-mcp-server/ ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-31github.com/nagarjunr/iot-mcp-servers ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from mqtt5-mcp-serverPass
- No critical advisory in the package or its dependencies64 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMQTT 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/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 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.
MQTT MCP questions
How do I add MQTT MCP to Claude Code?
Run claude mcp add --env 'MQTT_HOST=<MQTT_HOST>' --env 'MQTT_PASSWORD=<YOUR_MQTT_PASSWORD>' mqtt -- uvx mqtt5-mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add MQTT MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Which MQTT brokers are supported?
It works with any MQTT broker that supports the standard MQTT 5.0 wire protocol, such as Eclipse Mosquitto, EMQX, HiveMQ, AWS IoT Core, and Azure IoT Hub.
How does topic discovery work?
Since MQTT has no native topic-listing operation, the server approximates topic discovery by using retained messages.
How do I receive messages through the server?
Subscriptions are session-based; you first use start_subscription to register interest and buffer messages, then use get_messages to drain that buffer.