UniFi Dream Machine MCP Server Site Manager Telemetry

Overview

This MCP server collects telemetry from UniFi Site Manager and a local UniFi Dream Machine (UDM), normalizes it, and exposes it to Model Context Protocol (MCP) clients. It acts as a bridge between UniFi’s management APIs and systems that consume continuous telemetry streams — for example analytics backends, alerting systems, or visual dashboards. By centralizing Site Manager and on-premise Dream Machine metrics, it helps teams monitor network health, capacity, and client behavior in near real time.

The server is useful when you want a single, programmatic feed of UniFi telemetry without polling multiple APIs or parsing disparate outputs. It supports integration scenarios such as feeding telemetry into time-series databases, driving automated remediation, or enriching SIEM logs with network context.

Features

• Aggregates telemetry from UniFi Site Manager and a local Dream Machine
• Publishes structured telemetry over the Model Context Protocol (MCP)
• Configurable via environment variables or a YAML config file
• Runs as a standalone binary or container (Docker)
• Minimal operational footprint suitable for edge deployments
• Health checks and configurable logging level for production use
• Designed to be consumed by analytics, monitoring, and automation systems

Installation / Configuration

Two common install options are Docker (recommended for most users) and building from source.

Docker (quick start)

1. Create a docker-compose.yml (example below).
2. Supply credentials/configuration with environment variables or a mounted config file.
3. Start the service with docker-compose up -d.

Example docker-compose.yml:

version: "3.7"
services:
  mcp-unifi:
    image: sabler/mcp-unifi:latest
    container_name: mcp-unifi
    restart: unless-stopped
    environment:
      - SITE_MANAGER_URL=https://site-manager.example.com
      - SITE_MANAGER_TOKEN=eyJ...         # API token for Site Manager
      - UDM_HOST=192.168.1.1
      - UDM_USERNAME=admin
      - UDM_PASSWORD=secret
      - MCP_LISTEN_ADDR=0.0.0.0:7700
      - LOG_LEVEL=info
    volumes:
      - ./config.yml:/etc/mcp-unifi/config.yml:ro
    ports:
      - "7700:7700"

Build and run from source

# clone the repo
git clone https://github.com/sabler/mcp-unifi.git
cd mcp-unifi

# build (example; actual build tool may vary)
make build   # or run the appropriate build command shown in the repo

# run the binary with environment variables
./bin/mcp-unifi \
  --site-manager-url https://site-manager.example.com \
  --site-manager-token eyJ... \
  --udm-host 192.168.1.1 \
  --mcp-listen-addr 0.0.0.0:7700

Configuration options (common environment variables)

Config file (optional YAML)

site_manager:
  url: "https://site-manager.example.com"
  token: "eyJ..."

udm:
  host: "192.168.1.1"
  username: "admin"
  password: "secret"

mcp:
  listen_addr: "0.0.0.0:7700"

logging:
  level: "info"

Security notes

• Store API tokens and credentials securely (e.g., Docker secrets, Vault).
• If exposing MCP to untrusted networks, use a network-level ACL or TLS termination/proxy.
• Rotate Site Manager tokens according to your org policy.

Available Resources

• GitHub repository: https://github.com/sabler/mcp-unifi — source, issues, and releases
• MCP specification: consult the Model Context Protocol docs used by your ecosystem for client implementation details
• Example consumers: connect MCP output to a streaming consumer, a Prometheus exporter, or a logging pipeline (Grafana, InfluxDB, Kafka)

Use Cases

• Real-time performance monitoring
  • Stream per-radio and per-client metrics (RSSI, throughput, packet counts) to a metrics pipeline, enabling live dashboards and slicing by AP, SSID, or client device.
• Automated capacity planning
  • Aggregate historical telemetry to identify congested APs, peak hours, and required hardware upgrades.
• Proactive alerting and remediation
  • Feed telemetry into rules engines to trigger alerts on high packet loss, channel saturation, or failing backhaul links. Automations can throttle or reprovision to reduce impact.
• Troubleshooting and forensics
  • Combine MCP telemetry with DHCP/AAA/SIEM logs to trace user sessions, roaming events, and link-state regressions during incident investigation.
• Multi-site correlation
  • If you manage multiple UDMs and sites via Site Manager, centralize telemetry streams to compare performance across locations and detect systemic issues.

Getting Help and Contributing

For bugs, feature requests, and contributions, use the repository issues and pull requests on GitHub: https://github.com/sabler/mcp-unifi. Include relevant logs, config snippets (with secrets removed), and reproduction steps when reporting problems.