Icecast2mqtt – Lightweight MQTT bridge for Icecast radio streams metadata

SNMetamorph · August 23, 2026, 9:02am

Lightweight bridge that polls Icecast radio servers and publishes their live statistics to MQTT. Service includes Home Assistant MQTT auto discovery feature support, and if configured, stations show up as MQTT devices with sensors automatically and therefore ready for use in visualizations or automations. Metadata fetching happening in concurrent way and you could monitoring tens of Icecast servers in configuration without any problems.

GitHub Repository

Available metrics

Server-level

Sub-topic	Description
`version`	Icecast server version string
`server_start_date`	Server start time (ISO 8601)
`active_sources`	Number of currently active mountpoints

Per-stream

Sub-topic	Description
`listeners`	Current listener count
`stream_start_date`	Stream start time (ISO 8601)
`track`	Current song, “Artist - Title”

Suggestions on what other metrics should be also exposed are welcome.

Configuration

The service reads config.json from the working directory. A static JSON schema
(config.schema.json) is linked from the config via the
$schema key, so most IDEs (VS Code, JetBrains) provide completion, validation and inline
hints while you edit it. A ready-to-fill example lives in
config.json.example.

MQTT credentials come from environment variables, not from the config file.

Environment variable	Required	Description
`MQTT_BROKER`	yes	Broker URL, e.g. `tcp://mqtt.local:1883`
`MQTT_USERNAME`	no	MQTT username
`MQTT_PASSWORD`	no	MQTT password

Deployment with Docker

Prepare your config.json file (copy and edit config.json.example):
Use this preset for docker-compose.yml:

services:
  icecast2mqtt:
    image: ghcr.io/snmetamorph/icecast2mqtt:latest
    container_name: icecast2mqtt
    restart: unless-stopped
    environment:
      - MQTT_BROKER=${MQTT_BROKER:?set MQTT_BROKER in .env}
      - MQTT_USERNAME=${MQTT_USERNAME:-}
      - MQTT_PASSWORD=${MQTT_PASSWORD:-}
    volumes:
      - ./config.json:/app/config.json:ro

Create a .env file next to docker-compose.yml:

MQTT_BROKER=tcp://127.0.0.1:1883
MQTT_USERNAME=your_username
MQTT_PASSWORD=your_password

Start the service:

docker compose up -d

Your config.json is mounted into the container read-only, so editing it on the host and
restarting container is enough to apply changes.

Home Assistant integration

A short overview of how the bridge interoperates with Home Assistant:

When ha_discovery is set for a target in configuration file, the bridge publishes MQTT discovery messages under ha_autodiscovery_prefix on every poll.
Each Icecast server becomes a MQTT device identified by device_id with the friendly name from device_name.
Discovered entities have sensor class, the server-level ones are placed in the diagnostic entity category. Stream-level metrics are placed as regular sensor entities.

For now, only deployment with Docker available. Would be neat if somebody will make Home Assistant addon out of it.