The Grafana MQTT datasource plugin lets a dashboard subscribe to broker topics and draw values the moment they are published, with no database in between. In this tutorial you will install the plugin, connect it to broker.connectmq.com, build live panels from numeric and JSON payloads, and learn exactly when you should add a time-series database instead.
How the Grafana MQTT Datasource Works
Most Grafana data sources are query-based: a panel asks a database for a time range and draws the result. The MQTT data source is different. It is a streaming data source built on Grafana Live. When a panel opens, the Grafana server subscribes to the topic you specify, and every message is pushed to the browser over a WebSocket and appended to the chart.
That design has two consequences you should understand before building anything serious:
- Latency is excellent. A value published by a device shows up in the panel almost immediately, which is ideal for commissioning, live demos and control-room style views.
- There is no history. The plugin only shows what arrived while the panel was open. Reload the dashboard and the chart starts empty. You cannot zoom out to yesterday, because yesterday was never stored.
Keep both in mind. The MQTT data source is a window into the live stream, not a record of it.
Install the Plugin
The plugin ID is grafana-mqtt-datasource. On a native Grafana installation:
grafana cli plugins install grafana-mqtt-datasource
sudo systemctl restart grafana-server
Older Grafana versions use the grafana-cli binary instead of grafana cli. With Docker, let the container install it at startup:
services:
grafana:
image: grafana/grafana:11.3.0
ports:
- "3000:3000"
environment:
GF_INSTALL_PLUGINS: grafana-mqtt-datasource
volumes:
- grafana-data:/var/lib/grafana
volumes:
grafana-data:
Run docker compose up -d and open http://localhost:3000. The default login is admin / admin, and Grafana asks you to change it.
Configure the Connection
In Grafana, go to Connections, then Data sources, then Add data source, and search for MQTT. The settings page asks for a URI and optional credentials.
| Setting | Public test broker | Private broker (production) |
|---|---|---|
| URI | tcp://broker.connectmq.com:1883 |
tls://broker.connectmq.com:8883 |
| Username | empty | YOUR_USERNAME |
| Password | empty | YOUR_PASSWORD |
| TLS options | none | Leave CA empty; the Let's Encrypt certificate is publicly trusted |
Click Save and test. A green confirmation means the Grafana server, not your browser, reached the broker. That distinction matters in locked-down networks: the server needs outbound access to port 1883 or 8883. If your plugin version shows a client ID field and you connect to a managed broker that binds client IDs to credentials, enter the client ID issued with your username.
Publish Some Test Data
Choose a unique prefix such as connectmq/demo/a1b2c3 so your test topics stay separate on the public broker. This Bash loop publishes a plain numeric temperature every two seconds:
ID=a1b2c3
while true; do
T=$(awk -v r=$RANDOM 'BEGIN { printf "%.2f", 20 + r / 32767 * 5 }')
mosquitto_pub -h broker.connectmq.com -p 1883 -i "pub-$ID" \
-t "connectmq/demo/$ID/room1/temperature" -m "$T"
sleep 2
done
And this one publishes a JSON object with several values:
ID=a1b2c3
while true; do
T=$(awk -v r=$RANDOM 'BEGIN { printf "%.2f", 20 + r / 32767 * 5 }')
H=$(awk -v r=$RANDOM 'BEGIN { printf "%.1f", 40 + r / 32767 * 15 }')
mosquitto_pub -h broker.connectmq.com -p 1883 -i "pubjson-$ID" \
-t "connectmq/demo/$ID/room1/telemetry" \
-m "{\"temperature\": $T, \"humidity\": $H}"
sleep 2
done
For many devices at once, run the MQTT device simulator in Python and point panels at individual device topics.
Build a Live Panel with the Grafana MQTT Datasource
- Create a new dashboard and add a visualization.
- Select the MQTT data source.
- In the query editor, enter the topic, for example
connectmq/demo/a1b2c3/room1/temperature. - Choose the Time series visualization. Values begin to appear within seconds.
- Set the dashboard time range to something short, such as the last 5 minutes. Automatic refresh is not needed, because the panel is streaming.
For the JSON topic, the plugin turns each numeric key in the object into its own field, so temperature and humidity become two series in the same panel. Use field overrides to put humidity on a right-hand axis or give each series its own unit. Stat and Gauge panels work well for single current values; set their calculation to "Last" so they always show the newest reading.
Recent versions of the plugin accept the + and # wildcards in the topic field, which is handy for watching a group of sensors in one panel. If your version rejects wildcards, add one query per topic instead, as each panel can hold several queries.
Common Problems and Fixes
| Symptom | Cause | Fix |
|---|---|---|
| "Save and test" fails | Grafana server cannot reach the broker | Test from the server with mosquitto_sub; check firewalls and the URI scheme |
| Panel stays empty | Topic mismatch or nothing published yet | Confirm with mosquitto_sub -t "connectmq/demo/a1b2c3/#" -v |
| Chart empty after reload | Expected behaviour; no history is stored | Add a time-series database for history |
| Text instead of numbers | Payload contains units, such as 21.5 C |
Publish bare numbers or JSON numbers |
| Panel freezes in the browser | Very high message rate on one topic | Publish less often or aggregate before publishing |
| Unauthorized on a private broker | Wrong credentials or client ID | Copy the values from the broker portal again |
When to Add a Time-Series Database
The streaming data source is the right tool for a narrow set of jobs. As soon as you need history, aggregation or alerting over time, put a database between the broker and Grafana.
| Requirement | MQTT data source alone | Telegraf + InfluxDB + Grafana |
|---|---|---|
| Sub-second live view | Yes | Close, limited by flush interval |
| View last week | No | Yes |
| Averages, min/max per hour | No | Yes, in the query |
| Alert rules over time windows | Limited | Yes |
| Survives dashboard reload | No | Yes |
| Extra components to run | None | Two |
A common pattern combines both: a database-backed panel for the trend and a streaming panel for the current value. The Telegraf MQTT consumer tutorial shows how to write the same topics to InfluxDB, and the TIG stack with Docker Compose gives you the full stack in one file with provisioned dashboards. Once history exists, Grafana alerting on IoT sensor data becomes possible.
Notes for Production
The public broker is readable by everyone, so use it only for test data. For real equipment, connect Grafana to a private, TLS-protected broker. A hosted MQTT broker from ConnectMQ provides TLS on port 8883 and credentials from the portal, and Grafana connects to it like any other MQTT client. Remember that each Grafana server connection counts toward your plan's connection limit, which on the Serverless (Free) plan is 25.
For browser-only use cases where you do not want a Grafana server at all, a small web page using MQTT over WebSocket on port 8084 can display live values directly. To choose the right client stack for that or for device code, see the MQTT client libraries guide. The plugin's own Grafana MQTT data source page documents its current options.
Get Started with ConnectMQ
Point the plugin at broker.connectmq.com and you will have a live panel in minutes. When the dashboard is going to show real devices, run your broker on ConnectMQ, where you also get an in-browser MQTT client and a live topic explorer to check topics before wiring panels. Create a free Serverless broker at app.connectmq.com with no credit card required. Planning a bigger rollout? Our guide to the cloud MQTT broker covers what changes at scale.
Frequently Asked Questions
Does the Grafana MQTT datasource store data?
No. It streams messages to open panels through Grafana Live and keeps nothing once the panel closes. Use a time-series database such as InfluxDB when you need history.
Can I use wildcards in the topic field?
Recent plugin versions support + and #. On older versions, add one query per topic.
Which payload formats work with the plugin?
Plain numeric payloads and JSON objects with numeric values work best. Each numeric JSON key becomes a separate field in the panel.
Does the browser connect to the broker directly?
No. The Grafana server holds the MQTT connection and forwards data to browsers over Grafana Live, so only the server needs network access to the broker.
