Skip to content
Back to search

mcp-mqtt

Hardened MCP servers for Mosquitto, EMQX and NanoMQ MQTT brokers: publish/subscribe with allowlists, payload caps and rate limits

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bsommers--mcp-mqtt/badge.svg)](/listings/bsommers--mcp-mqtt)

HTML

<a href="/listings/bsommers--mcp-mqtt"><img src="/api/listings/bsommers--mcp-mqtt/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

uv sync
MQTT_HOST=localhost MQTT_PUBLISH_ALLOW='home/cmd/#' MQTT_SUBSCRIBE_ALLOW='home/#' uv run mcp-mosquitto

Register 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}`).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 153 lines
  1. <p align="center">
  2. <img src="docs/assets/logo.png" alt="mcp-mqtt: guarded MCP servers for Mosquitto, EMQX and NanoMQ" width="900">
  3. </p>
  4. <p align="center">
  5. <a href="https://bsommers.github.io/mcp-mqtt/"><img alt="site" src="https://img.shields.io/badge/site-live-00e5ff?style=flat-square&labelColor=050811"></a>
  6. <img alt="tests" src="https://img.shields.io/badge/tests-274%20passing-00e5ff?style=flat-square&labelColor=050811">
  7. <img alt="brokers" src="https://img.shields.io/badge/brokers-Mosquitto%20%C2%B7%20EMQX%20%C2%B7%20NanoMQ-38bdf8?style=flat-square&labelColor=050811">
  8. <img alt="security" src="https://img.shields.io/badge/security-deny--by--default-ff8a00?style=flat-square&labelColor=050811">
  9. <img alt="license" src="https://img.shields.io/badge/license-MIT-38bdf8?style=flat-square&labelColor=050811">
  10. </p>
  11. <p align="center">
  12. <img src="docs/assets/icons/icon-publish.svg" width="48" alt="publish" title="publish">
  13. <img src="docs/assets/icons/icon-subscribe.svg" width="48" alt="subscribe" title="subscribe">
  14. <img src="docs/assets/icons/icon-security.svg" width="48" alt="security" title="security">
  15. <img src="docs/assets/icons/icon-mosquitto.svg" width="48" alt="Mosquitto" title="Mosquitto">
  16. <img src="docs/assets/icons/icon-emqx.svg" width="48" alt="EMQX" title="EMQX">
  17. <img src="docs/assets/icons/icon-nanomq.svg" width="48" alt="NanoMQ" title="NanoMQ">
  18. </p>
  19. # mcp-mqtt
  20. Hardened [MCP](https://modelcontextprotocol.io) servers that let an LLM agent publish to and subscribe on
  21. **Mosquitto**, **EMQX** and **NanoMQ** MQTT brokers, with deny-by-default authorization and bounded, untrusted-flagged output.
  22. Site: <https://bsommers.github.io/mcp-mqtt/> · Part of [bilism.org](https://bilism.org) · Docs: [docs/](docs/README.md)
  23. ## Why mcp-mqtt
  24. 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.
  25. 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.
  26. 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](docs/purpose.md).
  27. ## Background
  28. MQTT carries device telemetry and control. Handing an agent a raw MQTT client means it can publish anywhere,
  29. subscribe to everything (`#`), flood the broker, and read attacker-controlled payloads as if they were instructions.
  30. These servers expose a small tool surface where every guard lives server-side.
  31. ## Relationship to forge
  32. [forge](https://github.com/bsommers/forge) generates MCP servers from OpenAPI specs only; MQTT is not OpenAPI, so these servers were
  33. hand-written to follow forge's layout (one module per broker profile plus shared core) and the secure-design-patterns
  34. MCP-001 (config from server env only), MCP-003 (dual-axis bounding), MCP-006 (stateless handlers) and MCP-008 (stdout is JSON-RPC only)
  35. rules. The MQTT-specific guards (topic allowlists, payload caps, rate limit, untrusted-payload flagging) are additions.
  36. ## Architecture
  37. ```
  38. LLM / MCP client
  39. | JSON-RPC over stdio (stdout = protocol only, logs -> stderr)
  40. v
  41. +-------------------------------+
  42. | brokers/{mosquitto,emqx, | per-broker entry point: shared tools + extras
  43. | nanomq}.py |
  44. +---------------+---------------+
  45. v
  46. +-------------------------------+ +--------------------+
  47. | server.py (tool handlers) |<-----| config.py | MQTT_* env only
  48. | rate limit -> guards -> I/O | +--------------------+
  49. +------+----------------+-------+
  50. | security.py | client.py (paho-mqtt, one short-lived connection per call)
  51. | allowlists, v
  52. | caps, flagging +--------> MQTT broker (TCP/TLS)
  53. +--------> broker REST API (EMQX / NanoMQ extras, httpx)
  54. ```
  55. ## Tools
  56. | Tool | Brokers | Purpose |
  57. |---|---|---|
  58. | `mqtt_publish` | all (absent if `MQTT_READ_ONLY=1`) | Publish to an allowlisted, wildcard-free topic |
  59. | `mqtt_subscribe` | all | Collect up to N messages for up to T seconds on an allowlisted filter |
  60. | `mqtt_get_retained` | all | Fetch retained messages matching a filter |
  61. | `mqtt_policy` | all | Show active limits and allowlists (no secrets) |
  62. | `mosquitto_sys_stats` | Mosquitto | Read `$SYS/broker/#` (needs `$SYS/#` in subscribe allowlist) |
  63. | `emqx_stats`, `emqx_list_clients`, `emqx_list_subscriptions` | EMQX | Read-only REST API helpers |
  64. | `nanomq_stats`, `nanomq_list_clients` | NanoMQ | Read-only REST API helpers |
  65. ## Configuration (environment)
  66. | Variable | Default | Meaning |
  67. |---|---|---|
  68. | `MQTT_HOST` / `MQTT_PORT` | `localhost` / `1883` (`8883` with TLS) | Broker address |
  69. | `MQTT_USERNAME` / `MQTT_PASSWORD` | unset | Credentials (refused over plaintext to non-loopback hosts) |
  70. | `MQTT_TLS` | off | `1` enables TLS |
  71. | `MQTT_TLS_CA` / `MQTT_TLS_CERT` / `MQTT_TLS_KEY` | unset | CA and client certificate files |
  72. | `MQTT_TLS_INSECURE` | off | `1` disables certificate and hostname verification (requires `MQTT_TLS=1`) |
  73. | `MQTT_PUBLISH_ALLOW` | empty (deny all) | Comma-separated topic patterns that may be published |
  74. | `MQTT_SUBSCRIBE_ALLOW` | empty (deny all) | Comma-separated filters that may be subscribed; requested filters must be covered |
  75. | `MQTT_READ_ONLY` | off | `1` removes `mqtt_publish` |
  76. | `MQTT_ALLOW_RETAIN` | off | `1` permits retained publishes |
  77. | `MQTT_MAX_QOS` | `1` | Highest QoS (0-2) |
  78. | `MQTT_MAX_PUBLISH_BYTES` | `65536` | Publish payload cap |
  79. | `MQTT_MAX_MESSAGE_BYTES` | `8192` | Per inbound message cap returned to the LLM |
  80. | `MQTT_MAX_MESSAGES` | `100` | Messages per subscribe call |
  81. | `MQTT_MAX_RESPONSE_BYTES` | `32768` | Total tool response budget |
  82. | `MQTT_RATE_LIMIT_PER_MINUTE` | `60` | Tool calls per minute (process-wide) |
  83. | `EMQX_API_URL`, `EMQX_API_KEY`, `EMQX_API_SECRET` | `http://localhost:18083` | EMQX REST access (server env only) |
  84. | `NANOMQ_API_URL`, `NANOMQ_API_USER`, `NANOMQ_API_PASSWORD` | `http://localhost:8081` | NanoMQ REST access (server env only) |
  85. ## Security model
  86. - **Deny by default**: empty allowlists permit nothing.
  87. - **No wildcards or `$`-topics on publish**; subscribe filters must be covered by the allowlist (no `#` escalation).
  88. - **Credentials never travel through tool inputs**; they come from the server environment only.
  89. - **Bounds**: payload size, message count, per-message size, total response size, wait time, topic length/depth, QoS, rate limit.
  90. - **Inbound payloads are untrusted**: returned in a structured field with `"untrusted": true`, truncated, and base64-encoded if binary. Treat as data, never instructions.
  91. - **stdout is protocol-only**; logging goes to stderr as JSON.
  92. - Tool handlers for publish/subscribe/retained/sys-stats are async and run broker I/O in worker threads, so a waiting `mqtt_subscribe` does not block other calls. (The EMQX/NanoMQ REST helpers and `mqtt_policy` are synchronous; REST calls block for at most 5 s.)
  93. ## Quickstart
  94. ```bash
  95. uv sync
  96. MQTT_HOST=localhost MQTT_PUBLISH_ALLOW='home/cmd/#' MQTT_SUBSCRIBE_ALLOW='home/#' uv run mcp-mosquitto
  97. ```
  98. Register with Claude Code or Claude Desktop: see `examples/claude_code_mcp_add.sh` and `examples/claude_desktop_config.json`.
  99. Client demos: `examples/01_publish_subscribe.py`, `02_sensor_telemetry.py`, `03_secure_policy_demo.py` (all take `--broker {mosquitto,emqx,nanomq}`).
  100. ## Documentation
  101. | Doc | Contents |
  102. |---|---|
  103. | [docs/purpose.md](docs/purpose.md) | Why, value, use cases, when not to use |
  104. | [docs/architecture.md](docs/architecture.md) | Components, flows, guard pipeline, threat model |
  105. | [docs/running.md](docs/running.md) | Install and run |
  106. | [docs/how-to.md](docs/how-to.md) | Recipes (Claude Code/Desktop, brokers, TLS, allowlists, read-only, limits) |
  107. | [docs/usermanual/](docs/usermanual/README.md) | Install, config reference, tool reference, troubleshooting |
  108. | [docs/SECURITY.md](docs/SECURITY.md) | Policy and honest limits |
  109. | [docs/TESTING.md](docs/TESTING.md) | Tests and coverage caveat |
  110. Also [CONTRIBUTING](CONTRIBUTING.md), [CHANGELOG](CHANGELOG.md), [LICENSE](LICENSE) (MIT).
  111. ## Testing
  112. ```bash
  113. docker compose -f docker/docker-compose.yml up -d # anonymous test brokers on 127.0.0.1:21883/21884/21885
  114. uv run pytest # unit + static gates
  115. uv run pytest -m integration # stdio end-to-end against the live brokers
  116. ```
  117. Integration tests skip a broker whose port is closed. Coverage under-reports broker/client code because the servers run in a subprocess ([docs/TESTING.md](docs/TESTING.md)). The compose brokers are for testing only (anonymous, loopback).
  118. ## Per-broker notes
  119. - **Mosquitto**: `mosquitto_sys_stats` reads `$SYS/broker/#`; add `$SYS/#` to `MQTT_SUBSCRIBE_ALLOW` deliberately. Publishing to `$SYS` is always blocked.
  120. - **EMQX**: create a read-only API key in the dashboard (Management > API Keys) and pass `EMQX_API_KEY`/`EMQX_API_SECRET` in the server env. Without them the REST helpers return an error; pub/sub still works.
  121. - **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.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.