--- title: "Configure the MQTT data source | Grafana Plugins documentation" description: "Configure the MQTT data source in Grafana to connect to your MQTT broker." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # 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. Expand table | Setting | Description | |---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Name** | A display name for this data source instance. | | **URI** | The URI of your MQTT broker. Include the scheme and port. Supported schemes: `tcp://` (unencrypted, default port `1883`), `tls://` (TLS-encrypted, default port `8883`), `ws://` (WebSocket, default port `80`), and `wss://` (WebSocket Secure, default port `443`). The aliases `mqtt://` (same as `tcp://`), `ssl://`, `tcps://`, and `mqtts://` (same as `tls://`) are also accepted. For example, `tcp://localhost:1883` or `tls://broker.example.com:8883`. If you omit the port, the default for the scheme is used. | | **Client ID** | An optional MQTT client identifier. If left empty, Grafana generates a random ID in the format `grafana_`. | ## Authentication If your broker requires credentials, configure them in the **Authentication** section. Expand table | Setting | Description | |--------------|--------------------------------------------------------------------------| | **Username** | The username for MQTT broker authentication. | | **Password** | The password for MQTT broker authentication. Stored securely in Grafana. | ## TLS authentication The MQTT data source supports TLS for encrypted connections and mutual TLS (mTLS) for client certificate authentication. Expand table | Setting | Description | |---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Use TLS Client Auth** | Enable to authenticate with a client certificate and private key. When enabled, the **TLS Configuration** section appears. | | **Skip TLS Verification** | Enable to skip verification of the broker’s TLS certificate chain and host name. Use this only for testing or when connecting to brokers with self-signed certificates. | | **With CA Cert** | Enable to provide a custom CA certificate for verifying the broker’s server certificate. When enabled, the **TLS Configuration** section appears. | When you enable **Use TLS Client Auth** or **With CA Cert**, configure the certificates in the **TLS Configuration** section that appears. Expand table | Setting | Description | |----------------------------|---------------------------------------------------------------------------------------------------------------------------| | **TLS CA Certificate** | The PEM-encoded CA certificate used to verify the broker’s server certificate. Required when **With CA Cert** is enabled. | | **TLS Client Certificate** | The PEM-encoded client certificate for mTLS authentication. Required when **Use TLS Client Auth** is enabled. | | **TLS Client Key** | The PEM-encoded private key for the client certificate. Required when **Use TLS Client Auth** is enabled. | ## 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)](/docs/grafana-cloud/connect-externally-hosted/private-data-source-connect/). ## 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](/docs/grafana/latest/administration/provisioning/#data-sources). YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml apiVersion: 1 datasources: - name: MQTT type: grafana-mqtt-datasource jsonData: uri: tcp://: username: clientID: tlsAuth: false tlsAuthWithCACert: false tlsSkipVerify: false secureJsonData: password: tlsCACert: tlsClientCert: tlsClientKey: ``` Replace the `` 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](https://registry.terraform.io/providers/grafana/grafana/latest/docs). For more information, refer to the [Grafana Terraform provider documentation](/docs/grafana/latest/as-code/infrastructure-as-code/terraform/). hcl ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```hcl resource "grafana_data_source" "mqtt" { name = "MQTT" type = "grafana-mqtt-datasource" json_data_encoded = jsonencode({ uri = "tcp://:" username = "" clientID = "" tlsAuth = false tlsAuthWithCACert = false tlsSkipVerify = false }) secure_json_data_encoded = jsonencode({ password = "" tlsCACert = "" tlsClientCert = "" tlsClientKey = "" }) } ``` Replace the `` 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](/docs/plugins/grafana-mqtt-datasource/latest/query-editor/) – Subscribe to topics and understand how data is formatted. - [Template variables](/docs/plugins/grafana-mqtt-datasource/latest/template-variables/) – Create dynamic dashboards with variable-driven topics. - [Troubleshoot MQTT data source issues](/docs/plugins/grafana-mqtt-datasource/latest/troubleshooting/) – Resolve common connection, authentication, and query problems.