Documentation Plugins MQTT Configure

Configure the MQTT data source

This document explains how to configure the MQTT data source to connect to your MQTT broker.

Before you begin

Before you configure the MQTT data source, ensure you have:

• Grafana permissions: Organization administrator role.
• MQTT broker access: The URI of a running MQTT v3.1.x broker that’s reachable from the Grafana server.
• Credentials: Username and password, or TLS certificates, if your broker requires authentication.

Add the data source

To add the MQTT data source to Grafana:

1. Click Connections in the left-side menu.
2. Click Add new connection.
3. Type MQTT in the search bar.
4. Select MQTT.
5. Click Add new data source.

Connection settings

Use the following settings to configure the connection to your MQTT broker.

Authentication

If your broker requires credentials, configure them in the Authentication section.

TLS authentication

The MQTT data source supports TLS for encrypted connections and mutual TLS (mTLS) for client certificate authentication.

When you enable Use TLS Client Auth or With CA Cert, configure the certificates in the TLS Configuration section that appears.

Private data source connect

Only for Grafana Cloud users. Private data source connect, or PDC, allows you to establish a private, secured connection between a Grafana Cloud instance, or stack, and data sources secured within a private network. This is useful when your MQTT broker isn’t reachable from Grafana Cloud directly. Click the drop-down to locate the URL for PDC.

When PDC is enabled in your Grafana instance, a Secure SOCKS Proxy configuration section appears on the data source settings page. For more information, refer to Private data source connect (PDC).

Verify the connection

After you configure the data source, click Save & test to verify the connection.

• A successful connection displays the message MQTT Connected.
• A failed connection displays the message MQTT Disconnected. Check your URI, credentials, and network connectivity, then try again.

Provision the data source

You can define and configure the MQTT data source using YAML files as part of Grafana’s provisioning system. For more information, refer to Provisioning Grafana.

YAML Copy

apiVersion: 1

datasources:
  - name: MQTT
    type: grafana-mqtt-datasource
    jsonData:
      uri: tcp://<BROKER_HOST>:<BROKER_PORT>
      username: <USERNAME>
      clientID: <CLIENT_ID>
      tlsAuth: false
      tlsAuthWithCACert: false
      tlsSkipVerify: false
    secureJsonData:
      password: <PASSWORD>
      tlsCACert: <CA_CERTIFICATE_PEM>
      tlsClientCert: <CLIENT_CERTIFICATE_PEM>
      tlsClientKey: <CLIENT_KEY_PEM>

Replace the <PLACEHOLDER> values with your broker-specific settings. Omit any secureJsonData fields that don’t apply to your configuration.

Provision the data source with Terraform

You can manage the MQTT data source as code using the Grafana Terraform provider. For more information, refer to the Grafana Terraform provider documentation.

hcl Copy

resource "grafana_data_source" "mqtt" {
  name = "MQTT"
  type = "grafana-mqtt-datasource"

  json_data_encoded = jsonencode({
    uri              = "tcp://<BROKER_HOST>:<BROKER_PORT>"
    username         = "<USERNAME>"
    clientID         = "<CLIENT_ID>"
    tlsAuth          = false
    tlsAuthWithCACert = false
    tlsSkipVerify    = false
  })

  secure_json_data_encoded = jsonencode({
    password      = "<PASSWORD>"
    tlsCACert     = "<CA_CERTIFICATE_PEM>"
    tlsClientCert = "<CLIENT_CERTIFICATE_PEM>"
    tlsClientKey  = "<CLIENT_KEY_PEM>"
  })
}

Replace the <PLACEHOLDER> values with your broker-specific settings. Omit any secure_json_data_encoded fields that don’t apply to your configuration.

Next steps

• MQTT query editor – Subscribe to topics and understand how data is formatted.
• Template variables – Create dynamic dashboards with variable-driven topics.
• Troubleshoot MQTT data source issues – Resolve common connection, authentication, and query problems.