Documentation

Connect Zigbee2MQTT to ZigStream

A one-file extension forwards your Zigbee2MQTT messages to your ZigStream account. The whole setup takes about five minutes and requires no changes to your MQTT broker.

On this page

Requirements

Zigbee2MQTT 1.36 or newer, running as a service or container.
Write access to the Zigbee2MQTT data/ folder.
Outbound HTTPS on port 443. No inbound ports or port forwarding.
A ZigStream account and one API key.

1. Generate an API key

Open your dashboard, go to Settings → API keys and create a key named after the host running Zigbee2MQTT.

Keys are shown once, are scoped to your account, and can be revoked at any time without touching your other integrations.

2. Install the forwarder

Download the extension into the Zigbee2MQTT extension folder.

# from your Zigbee2MQTT host
cd /opt/zigbee2mqtt/data
mkdir -p extension
curl -fsSL https://cdn.zigstream.dev/http-forwarder.js \
  -o extension/http-forwarder.js

3. configuration.yaml reference

Add the following blocks todata/configuration.yaml.

advanced:
  enable_external_js: true

http_forwarder:
  endpoint: "https://www.zigstream.app/ingest"
  token: "mk_live_xxxxxxxxxxxxxxxx"
  batch_size: 5             # messages per request
  flush_interval_ms: 5000   # seconds between pushes      
  exclude:
    - "bridge/logging"

Option	Type	Default	Description
`endpoint`	string	—	Ingest URL. Use the regional endpoint shown in your dashboard.
`token`	string	—	Scoped API key. Treat it as a secret and rotate it from Settings.
`batch_interval`	number	5	Seconds between pushes. Lower means fresher data and more requests.
`batch_max`	number	200	Maximum messages per request before an early flush.
`include_availability`	boolean	true	Forward online and offline availability events.
`exclude`	string[]	[]	Topic patterns to drop locally before anything leaves your network.

4. Restart & verify

Restart Zigbee2MQTT. Watch its log forhttp_forwarder: started.

Within one batch interval, your devices should appear under Devices in your dashboard.

Troubleshooting

No devices appear: confirm enable_external_js: true is set. Zigbee2MQTT 2.11+ disables external extensions by default.
401 errors in the log: the token was revoked or mistyped. Generate a fresh one from API keys.
429 errors: you are exceeding your plan’s ingest rate. Increasebatch_interval or upgrade your plan.

API & MCP endpoint

The same API key authenticates the REST API and the MCP endpoint at POST /mcp.

An AI agent can call list_devices,get_device_history, andget_usage_summary, all scoped to your account.