> AI agents: this is one page from Mammoth Analytics documentation. The index of all pages as Markdown is https://mammoth.io/docs/llms.txt. Append `.md` to any docs URL, or send `Accept: text/markdown`, to get Markdown.

# Import MQTT messages from a broker into Mammoth

> Connect Mammoth to an MQTT broker, subscribe to a topic for a collection window of 1 to 600 seconds, and save the IoT messages it receives as a dataset.

The MQTT connector subscribes to a topic on an MQTT broker and saves the messages it receives as a dataset, for example sensor readings from IoT devices. Open it from **Data Library** > **New dataset** > **Connectors** and search for **MQTT**. Project Admins create the connection; Project Editors can start datasets from a connection the project already has. Which connectors you can add depends on your plan.

## What you can bring in from MQTT

- The messages published on one topic while Mammoth listens, during a collection window you set.
- One batch of messages per run, imported as rows. A JSON message's fields become columns. Each row also gets `_timestamp` (when Mammoth received the message) and `_topic`.

## Before you connect MQTT

You need:

- A broker host reachable from the internet, and its port.
- A username and password, if the broker requires them. Leave them blank for anonymous access.
- A topic that is publishing messages.

## Connect an MQTT broker to Mammoth

1. Go to the **Data Library**, click **New dataset**, and choose **Connectors**.
2. Search for **MQTT** and click its tile. The connector workspace opens with the **Chat** showing. See [Connect a database or app](https://mammoth.io/docs/learn/get-data-in/connect-a-source/) for the shared steps.
3. Enter the connection details below and connect.

| Field | What to enter |
| --- | --- |
| **Broker Host** | The broker address, such as `broker.hivemq.com` |
| **Port** | Default `1883`, or `8883` for TLS |
| **Username** | Optional |
| **Password** | Optional |
| **Name** | Optional label for this connection, such as `Factory Floor Broker` |



When the port is `8883`, Mammoth connects over TLS.

## Choose the MQTT topic and collection window

The MQTT connector's own setup form asks:

| Setting | What it does |
| --- | --- |
| **Topic** | The topic to subscribe to, such as `sensors/factory1/temperature` |
| **Collection Window (seconds)** | How long Mammoth listens for messages, from 1 to 600 seconds, for example `60` |

Mammoth checks the topic before saving. **Topic is active and receiving messages.** means it's ready. In the connector workspace, you can tell the chat which topic you want.

## Refresh MQTT data and choose an update method

After you save, an MQTT dataset's **Update method** offers two options:

| Update method | What it does |
| --- | --- |
| **Replace all data** | Keeps only the messages from the latest run |
| **Add to existing data** | Adds each run's messages to the rows you already have |

MQTT refreshes don't use a key column. To collect new messages on a schedule, use a [Dataset Refresh](https://mammoth.io/docs/learn/automate/refresh-a-dataset/) automation.

## MQTT limits

- **Collection Window (seconds)**: a whole number from 1 to 600.
- One run keeps at most 10,000 messages. Messages after that, within the same window, aren't imported.

## Troubleshoot MQTT connections

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| **No messages received. Ensure the broker is running and the topic is active.** | Nothing published to the topic during the window | Check something is publishing to the topic, or lengthen the window |
| "Collection window must be between 1 and 600 seconds." | The window is outside the allowed range | Enter a whole number of seconds from 1 to 600 |
| "Topic is required." | The topic is empty | Enter the topic to subscribe to |

## Related

- [Apache Kafka](https://mammoth.io/docs/learn/get-data-in/connectors/kafka/): read messages from a Kafka topic.
- [Receive data by webhook](https://mammoth.io/docs/learn/get-data-in/webhooks/): let devices or systems push data to Mammoth.
- [Connect a database or app](https://mammoth.io/docs/learn/get-data-in/connect-a-source/): the shared connector workspace steps.
- [Refresh a dataset](https://mammoth.io/docs/learn/automate/refresh-a-dataset/): collect new messages on a schedule.
- [Manage saved connections](https://mammoth.io/docs/learn/get-data-in/connections/): reuse or remove this connection.

---
Source: https://mammoth.io/docs/learn/get-data-in/connectors/mqtt.md · Updated: 2026-11-08