mcp-mqtt
Provides hardened MCP tools for interacting with MQTT brokers such as Mosquitto, EMQX, and NanoMQ, enabling agents to publish to allowlisted topics, subscribe to messages, fetch retained messages, inspect active policy limits, and access broker-specific stats or client metadata through guarded, deny-by-default operations.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcp-mqtt
Hardened MCP servers that let an LLM agent publish to and subscribe on Mosquitto, EMQX and NanoMQ MQTT brokers, with deny-by-default authorization and bounded, untrusted-flagged output.
Site: https://bsommers.github.io/mcp-mqtt/ · Part of bilism.org · Docs: docs/
Why mcp-mqtt
LLM agents increasingly need to observe and act on IoT, sensor and event systems, and MQTT is the common bus. A naive broker-to-LLM bridge is risky: unbounded payloads, wildcard subscriptions, prompt injection through message payloads, and credentials in tool parameters. We found no hardened MCP option for Mosquitto, EMQX and NanoMQ, so this project provides one.
Value: deny-by-default allowlists, size/count/rate bounds, inbound payloads flagged untrusted, one consistent tool surface across the three brokers plus broker-specific extras, and integration tests against real brokers.
Use cases: sensor monitoring and summarisation, incident triage from broker stats, controlled device commands over one allowlisted topic, home automation, NanoMQ edge deployments, dev/test of MQTT systems, and a read-only observability mode. Not for: general message routing, high-throughput streaming, long-lived subscriptions, or per-client authorization. Details: docs/purpose.md.
Related MCP server: OMNI-MQTT-MCP
Background
MQTT carries device telemetry and control. Handing an agent a raw MQTT client means it can publish anywhere,
subscribe to everything (#), flood the broker, and read attacker-controlled payloads as if they were instructions.
These servers expose a small tool surface where every guard lives server-side.
Relationship to forge
forge generates MCP servers from OpenAPI specs only; MQTT is not OpenAPI, so these servers were hand-written to follow forge's layout (one module per broker profile plus shared core) and the secure-design-patterns MCP-001 (config from server env only), MCP-003 (dual-axis bounding), MCP-006 (stateless handlers) and MCP-008 (stdout is JSON-RPC only) rules. The MQTT-specific guards (topic allowlists, payload caps, rate limit, untrusted-payload flagging) are additions.
Architecture
LLM / MCP client
| JSON-RPC over stdio (stdout = protocol only, logs -> stderr)
v
+-------------------------------+
| brokers/{mosquitto,emqx, | per-broker entry point: shared tools + extras
| nanomq}.py |
+---------------+---------------+
v
+-------------------------------+ +--------------------+
| server.py (tool handlers) |<-----| config.py | MQTT_* env only
| rate limit -> guards -> I/O | +--------------------+
+------+----------------+-------+
| security.py | client.py (paho-mqtt, one short-lived connection per call)
| allowlists, v
| caps, flagging +--------> MQTT broker (TCP/TLS)
+--------> broker REST API (EMQX / NanoMQ extras, httpx)Tools
Tool | Brokers | Purpose |
| all (absent if | Publish to an allowlisted, wildcard-free topic |
| all | Collect up to N messages for up to T seconds on an allowlisted filter |
| all | Fetch retained messages matching a filter |
| all | Show active limits and allowlists (no secrets) |
| Mosquitto | Read |
| EMQX | Read-only REST API helpers |
| NanoMQ | Read-only REST API helpers |
Configuration (environment)
Variable | Default | Meaning |
|
| Broker address |
| unset | Credentials (refused over plaintext to non-loopback hosts) |
| off |
|
| unset | CA and client certificate files |
| off |
|
| empty (deny all) | Comma-separated topic patterns that may be published |
| empty (deny all) | Comma-separated filters that may be subscribed; requested filters must be covered |
| off |
|
| off |
|
|
| Highest QoS (0-2) |
|
| Publish payload cap |
|
| Per inbound message cap returned to the LLM |
|
| Messages per subscribe call |
|
| Total tool response budget |
|
| Tool calls per minute (process-wide) |
|
| EMQX REST access (server env only) |
|
| NanoMQ REST access (server env only) |
Security model
Deny by default: empty allowlists permit nothing.
No wildcards or
$-topics on publish; subscribe filters must be covered by the allowlist (no#escalation).Credentials never travel through tool inputs; they come from the server environment only.
Bounds: payload size, message count, per-message size, total response size, wait time, topic length/depth, QoS, rate limit.
Inbound payloads are untrusted: returned in a structured field with
"untrusted": true, truncated, and base64-encoded if binary. Treat as data, never instructions.stdout is protocol-only; logging goes to stderr as JSON.
Tool handlers for publish/subscribe/retained/sys-stats are async and run broker I/O in worker threads, so a waiting
mqtt_subscribedoes not block other calls. (The EMQX/NanoMQ REST helpers andmqtt_policyare synchronous; REST calls block for at most 5 s.)
Quickstart
uv sync
MQTT_HOST=localhost MQTT_PUBLISH_ALLOW='home/cmd/#' MQTT_SUBSCRIBE_ALLOW='home/#' uv run mcp-mosquittoRegister with Claude Code or Claude Desktop: see examples/claude_code_mcp_add.sh and examples/claude_desktop_config.json.
Client demos: examples/01_publish_subscribe.py, 02_sensor_telemetry.py, 03_secure_policy_demo.py (all take --broker {mosquitto,emqx,nanomq}).
Documentation
Doc | Contents |
Why, value, use cases, when not to use | |
Components, flows, guard pipeline, threat model | |
Install and run | |
Recipes (Claude Code/Desktop, brokers, TLS, allowlists, read-only, limits) | |
Install, config reference, tool reference, troubleshooting | |
Policy and honest limits | |
Tests and coverage caveat |
Also CONTRIBUTING, CHANGELOG, LICENSE (MIT).
Testing
docker compose -f docker/docker-compose.yml up -d # anonymous test brokers on 127.0.0.1:21883/21884/21885
uv run pytest # unit + static gates
uv run pytest -m integration # stdio end-to-end against the live brokersIntegration tests skip a broker whose port is closed. Coverage under-reports broker/client code because the servers run in a subprocess (docs/TESTING.md). The compose brokers are for testing only (anonymous, loopback).
Per-broker notes
Mosquitto:
mosquitto_sys_statsreads$SYS/broker/#; add$SYS/#toMQTT_SUBSCRIBE_ALLOWdeliberately. Publishing to$SYSis always blocked.EMQX: create a read-only API key in the dashboard (Management > API Keys) and pass
EMQX_API_KEY/EMQX_API_SECRETin the server env. Without them the REST helpers return an error; pub/sub still works.NanoMQ: enable the HTTP API (port 8081) and set
NANOMQ_API_USER/NANOMQ_API_PASSWORD. Without them the REST helpers return an error; pub/sub still works.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Real-time MCP & A2A prompt-injection, jailbreak, and tool-schema poisoning firewall for AI agents.
Real-time prompt injection filtering, MCP payload inspection, and A2A trust scoring.
Credential broker for AI agents: scoped, revocable API access with policy enforcement and audit.
Security gateway for AI agents: policy, approval, and audited execution, no secrets shared.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables LLM agents to interact with MQTT brokers through publish, subscribe, and query operations. Provides fine-grained topic permissions with wildcard support for secure IoT device communication and sensor data access.13 PyPI2BSD 3-Clause
- AlicenseBqualityDmaintenanceEnables AI assistants to publish and subscribe to MQTT topics with configurable transport options (STDIO, Streamable HTTP, SSE), supporting both local development and web deployments with flexible broker authentication.2MIT
- AlicenseNot gradedqualityBmaintenanceEnables LLM agents to securely monitor and control MQTT devices for building automation, industrial control, and smart home systems through a standardized MCP interface.25MIT
- FlicenseNot gradedqualityDmaintenanceProvides MQTT communication capabilities for Large Language Models and other clients, enabling connections to MQTT brokers, publishing and subscribing to topics, and managing real-time messaging workflows.-