Skip to content

MCP MQTT

This guide enables generic MQTT integration through the local Dockerized mqtt-mcp server registered in .mcp.json.

Scope

Current implementation in this repository provides:

  • Docker-only MCP transport
  • Pinned immutable runtime image digest
  • Generic MQTT publish/receive capabilities
  • Default broker routing via environment variables

Runtime image: ghcr.io/ezhuk/mqtt-mcp:latest

1. Prepare credentials in Bitwarden

Expected Bitwarden item:

  • Item name: MQTT MCP
  • Field MQTT_BROKER_URL: broker URL, for example mqtt://host:1883
  • Optional field MQTT_USERNAME: broker username
  • Optional field MQTT_PASSWORD: broker password
  • Optional field MQTT_BASE_TOPIC: defaults to zigbee2mqtt for current ZigBee workflows

Hydrate local .env from vault fields:

just bw-mqtt-credentials-pull

2. Validate MCP wiring

Run from the hermetic Nix shell:

just sync-ai
just mcp-health

Expected summary includes:

  • mqtt MCP docker image: ghcr.io/ezhuk/mqtt-mcp@sha256:<digest>

3. Runtime mapping

The server uses these environment variables:

  • MQTT_MCP_MQTT__HOST
  • MQTT_MCP_MQTT__PORT
  • MQTT_MCP_MQTT__USERNAME
  • MQTT_MCP_MQTT__PASSWORD

This repository maps them automatically from the hydrated .env values.

4. Example prompts

In your MCP-capable client, run prompts similar to:

Use the mqtt MCP server to publish {"state":"ON"} to topic "devices/lamp/set".

Use the mqtt MCP server to receive one message from topic "devices/lamp/state" with a 20 second timeout.

Troubleshooting

  • Connection failures: verify broker reachability and MQTT_BROKER_URL value.
  • Authentication failures: verify MQTT_USERNAME and MQTT_PASSWORD, then re-run just bw-mqtt-credentials-pull.