Hardened MQTT for LLM agents

Let an agent publish to and subscribe on Mosquitto, EMQX and NanoMQ, with deny-by-default allowlists and bounded, untrusted-flagged output.

10tools
3brokers
270tests
uv sync && uv run mcp-mosquitto

Why mcp-mqtt

LLM agents need a safe bridge to MQTT, which carries device telemetry and control. A naive bridge lets the agent publish anywhere, subscribe to everything (#), flood the broker, and read attacker-controlled payloads as instructions. Naive bridges risk:

  • unbounded payloads
  • wildcard subscriptions
  • prompt injection via payloads
  • credentials in tool parameters

Read the full motivation

Value proposition

Value proposition in detail

Key use cases

IoT sensor monitoring

Subscribe to telemetry and let the agent summarise trends and anomalies.

Ops triage via broker stats

Use read-only stats and client listings on EMQX, NanoMQ and Mosquitto $SYS.

Controlled device commands

Publish only to an allowlisted command topic such as home/commands/#.

Home automation

Query state and issue narrowly scoped commands from natural language.

Edge with NanoMQ

Same tool surface for lightweight edge brokers.

MQTT dev and test

Inspect topics, retained messages and payloads while building.

Read-only observability

Set MQTT_READ_ONLY=1 and mqtt_publish disappears.

More on use cases

When not to use it

It is not for high-throughput streaming or bridging: each call opens a short-lived connection, responses are capped, and tool handlers are synchronous, so a blocking subscribe delays other calls on the same process. It is also not a substitute for broker-side ACLs and authentication.

Choose your broker

Mosquitto

Adds mosquitto_sys_stats reading $SYS/broker/#. Add $SYS/# to MQTT_SUBSCRIBE_ALLOW deliberately; publishing to $SYS is always blocked.

uv run mcp-mosquitto

Diagrams

Security by default

Tool explorer


10 tools shown

mqtt_publishmosquittoemqxnanomq

Publish to an allowlisted, wildcard-free topic. Absent when MQTT_READ_ONLY=1.

mqtt_subscribemosquittoemqxnanomq

Collect up to N messages for up to T seconds on an allowlisted filter.

mqtt_get_retainedmosquittoemqxnanomq

Fetch retained messages matching a filter.

mqtt_policymosquittoemqxnanomq

Show active limits and allowlists (no secrets).

mosquitto_sys_statsmosquitto

Read $SYS/broker/#. Needs $SYS/# in the subscribe allowlist.

emqx_statsemqx

Read-only EMQX REST API stats.

emqx_list_clientsemqx

Read-only EMQX connected-client listing.

emqx_list_subscriptionsemqx

Read-only EMQX subscription listing.

nanomq_statsnanomq

Read-only NanoMQ REST API stats.

nanomq_list_clientsnanomq

Read-only NanoMQ client listing.

Runnable examples

Run the Mosquitto server

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

Register with Claude Code

claude mcp add mosquitto \
  -e MQTT_HOST=localhost -e MQTT_PORT=1883 \
  -e MQTT_PUBLISH_ALLOW='home/commands/#' -e MQTT_SUBSCRIBE_ALLOW='home/#,$SYS/#' \
  -- uv run --directory "$REPO" mcp-mosquitto

Start test brokers and run tests

docker compose -f docker/docker-compose.yml up -d
uv run pytest
uv run pytest -m integration

Publish/subscribe round-trip demo

uv run python examples/01_publish_subscribe.py --broker mosquitto

Secure policy demo

uv run python examples/03_secure_policy_demo.py --broker mosquitto

Documentation hub