UniFi MCP Server

mcp-name: io.github.mikeholownych/unifi-mcp

Ein MCP-Server (Model Context Protocol), der KI-Assistenten wie Claude Zugriff auf Verwaltungs- und Analysefunktionen für UniFi-Network- und UniFi-Protect-Infrastrukturen bietet.

Danksagung: Dieses Projekt entstand als Fork von gbassaragh/Unifi-mcp und hat sich seitdem zu einem vollständig eigenständigen Projekt entwickelt. Dank an @gbassaragh für den hervorragenden Ausgangspunkt.

Verbesserungen gegenüber dem Upstream

• Korrekte Routenführung der lokalen Sitzungsauthentifizierung – in UNIFI_MODE=local verwenden Anfragen jetzt korrekt die traditionelle Controller-API (/proxy/network) mit Cookie- und CSRF-Sitzungsauthentifizierung. Der Upstream hat unabhängig vom Modus immer über die Integrations-API geroutet.

• Modusabhängige Basis-URL-Auflösung – api_base_url respektiert jetzt den konfigurierten Authentifizierungsmodus, anstatt bedingungslos den Integrations-API-Endpunkt zurückzugeben.

• Erweiterte Testsuite – 57 erfolgreiche Tests, die Konfiguration, Netzwerk-Client-Verhalten, Server-Tool-Registrierung und Protect-Integrationen abdecken.

Related MCP server: UniFi MCP Server

Funktionen

UniFi Network

• Geräteverwaltung: UniFi-Geräte (APs, Switches, Router) auflisten, neu starten, lokalisieren und aktualisieren

• Client-Verwaltung: Verbundene Clients überwachen, blockieren/entsperren, Verkehrsstatistiken anzeigen

• Site-Verwaltung: Site-Health, Netzwerkkonfigurationen, VLANs und WLAN-Einstellungen anzeigen

• Statistiken und Überwachung: Ereignisse, Alarme, Geschwindigkeitstests und DPI-Statistiken

• KI-gestützte Einblicke: Netzwerkanalyse, Optimierungsempfehlungen und Fehlerbehebung

UniFi Protect

• Kameraverwaltung: Kameras auflisten, Status anzeigen, Live-Snapshots abrufen

• Systemüberwachung: NVR-Status, Kamera-Health-Zusammenfassungen

• Zubehör: Lichter, Sensoren, Klingeln und Viewer verwalten

• Liveviews: Auf konfigurierte Kamera-Ansichtslayouts zugreifen

Unterstützung mehrerer Geräte

• Konfiguration mehrerer UniFi-Geräte (Gateways, NVRs usw.)

• Gezielte Ansteuerung bestimmter Geräte über den Namen – alle Netzwerk- und Protect-Tools akzeptieren einen optionalen Parameter device

• Gerätespezifische API-Schlüssel: Jedes konfigurierte Gerät authentifiziert sich mit seinem eigenen Schlüssel

• Mischung aus Network- und Protect-Diensten über mehrere Geräte hinweg

Authentifizierungsmodi

Bei Verwendung von API-Schlüsseln (Integrations-API) ist eine Teilmenge der Controller-Funktionen nur über die klassische Sitzungsauthentifizierung (UNIFI_MODE=local) verfügbar: Netzwerkereignisse, Alarme, DPI-Statistiken, Geschwindigkeitstests, WLAN-Konfigurationen, Firewall-Regeln, Port-Profile und Routing-Tabellen. Tools für diese Funktionen geben eine klare Fehlermeldung mit Hinweisen zur Aktivierung zurück, anstatt stillschweigend zu scheitern. Insight-Tools degradieren graziös und melden Dateneinschränkungen.

Hinweis zu lokalen Konten: SSO-/Ubiquiti-Konto-Administratoren, die durch MFA geschützt sind, können die Sitzungsanmeldung nicht abschließen. Erstellen Sie für UNIFI_MODE=local einen lokalen Administrator auf Ihrer Konsole (Restrict to Local Access Only).

Agent-Fähigkeiten

Mitgelieferte Fähigkeiten (in skills/) vermitteln Agenten bewährte Arbeitsabläufe für diesen Server – einschließlich controllerspezifischer Stolperfallen (Network 10 entfernte Endpunkte, Zone-Pair-Regeln, WPA3-Transition).

Vollständige Dokumentation: Siehe SKILLS.md für Anleitung, erwartete Ergebnisse, Fehlerbehebung und wie Sie neue Funktionen anfragen können.

Kurzreferenz

So funktionieren die Fähigkeiten

Beschreiben Sie Ihr Problem einfach natürlich – der Agent ordnet Ihrer Anfrage die passende Fähigkeit zu und folgt ihrem Arbeitsablauf:

• »Mein Internet ist down« → unifi-internet-down diagnostiziert WAN, Modem, Gateway

• »Wer ist in meinem WLAN?« → unifi-whos-home listet Geräte auf und markiert Unbekannte

• »Auditiere mein Netzwerk« → unifi-network-audit erstellt einen vollständigen Health-Bericht

• »Richte meinen neuen Fernseher ein« → unifi-setup-new-device führt durch das WLAN-Pairing

Schreibgeschützte Fähigkeiten (oben markiert) verändern Ihr Netzwerk – sie fragen vor der Anwendung von Änderungen immer um Genehmigung.

Fähigkeiten für nicht-technische Benutzer vermeiden Fachjargon, übersetzen jeden technischen Begriff und verlangen vor disruptiven Aktionen eine Bestätigung.

Installation (pro Projekt): Kopieren Sie in .claude/skills/:

git clone https://github.com/mikeholownych/unifi-mcp.git
mkdir -p .claude/skills && cp -r unifi-mcp/skills/* .claude/skills/

Siehe SKILLS.md für die vollständige Anleitung, erwartete Ergebnisse, Fehlerbehebung und wie Sie neue Funktionen anfragen können.

Fähigkeiten referenzieren MCP-Tools über ihre einfachen Namen (get_firewall_policies, …); Ihr MCP-Client setzt das Präfix automatisch davor.

Unterstützte Hardware

• UniFi Dream Machine (UDM, UDM-Pro, UDM-SE)

• UniFi Cloud Gateway (UCG-Ultra, UCG-Fiber)

• UniFi Network Video Recorder (UNVR, UNVR-Pro)

• UniFi Network Application (selbst gehostet)

• Traditionelle Cloud Key (Gen1, Gen2, Gen2+)

Installation

Mit uv (empfohlen)

# Clone the repository
git clone https://github.com/mikeholownych/unifi-mcp.git
cd unifi-mcp

# Install dependencies
uv sync

Mit pip

pip install -e .

Konfiguration

Erstellen Sie im Projektstamm eine .env-Datei (oder setzen Sie Umgebungsvariablen). Siehe .env.example für alle Optionen.

Multi-Geräte-Konfiguration (empfohlen)

Konfigurieren Sie mehrere UniFi-Geräte mit verschiedenen Diensten:

UNIFI_DEVICES='[
  {
    "name": "main-gateway",
    "url": "https://192.168.1.1",
    "api_key": "your-gateway-api-key",
    "services": ["network"],
    "site": "default"
  },
  {
    "name": "nvr",
    "url": "https://192.168.1.2",
    "api_key": "your-nvr-api-key",
    "services": ["network", "protect"],
    "site": "default"
  }
]'
UNIFI_VERIFY_SSL=false

Felder der Gerätekonfiguration:

Hinweis: Die Felder username und password werden nur für die Protect-Ereignis-Tools benötigt (Bewegungsereignisse, intelligente Erkennungen). Grundlegende Kameraoperationen funktionieren bereits mit dem API-Schlüssel.

So erstellen Sie einen API-Schlüssel:

1. Melden Sie sich bei Ihrem UniFi-Controller an

2. Gehen Sie zu Settings → Control Plane → API

3. Erstellen Sie einen neuen API-Schlüssel mit den entsprechenden Berechtigungen

Legacy-Konfiguration (einzelnes Gerät)

Aus Gründen der Abwärtskompatibilität wird die Konfiguration einzelner Geräte weiterhin unterstützt:

UNIFI_MODE=local_api_key
UNIFI_CONTROLLER_URL=https://192.168.1.1
UNIFI_CLOUD_API_KEY=your-api-key
UNIFI_SITE=default
UNIFI_VERIFY_SSL=false

Lokale Sitzungsauthentifizierung (traditionell)

Für den vollen Funktionsumfang mit Benutzername/Passwort-Authentifizierung:

UNIFI_MODE=local
UNIFI_CONTROLLER_URL=https://192.168.1.1
UNIFI_USERNAME=local-admin
UNIFI_PASSWORD=your-password
UNIFI_SITE=default
UNIFI_IS_UDM=true
UNIFI_VERIFY_SSL=false

Cloud-API (api.ui.com)

Für den Zugriff auf die Ubiquiti-Cloud-API:

UNIFI_MODE=cloud
UNIFI_CLOUD_API_KEY=your-api-key

Holen Sie sich Ihren API-Schlüssel von unifi.ui.com → Bereich API.

Verwendung mit Claude Desktop

Fügen Sie Folgendes zu Ihrer Claude-Desktop-Konfiguration hinzu (~/.config/claude/claude_desktop_config.json unter Linux oder ~/Library/Application Support/Claude/claude_desktop_config.json unter macOS):

{
  "mcpServers": {
    "unifi": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/unifi-mcp", "python", "-m", "unifi_mcp.server"],
      "env": {
        "UNIFI_DEVICES": "[{\"name\":\"gateway\",\"url\":\"https://192.168.1.1\",\"api_key\":\"your-key\",\"services\":[\"network\"]},{\"name\":\"nvr\",\"url\":\"https://192.168.1.2\",\"api_key\":\"your-key\",\"services\":[\"network\",\"protect\"]}]",
        "UNIFI_VERIFY_SSL": "false"
      }
    }
  }
}

Verwendung mit Claude Code / opencode

# Add the MCP server
claude mcp add unifi -- uv run --directory /path/to/unifi-mcp python -m unifi_mcp.server

Oder in opencode.json:

{
  "mcp": {
    "unifi": {
      "type": "local",
      "command": ["/path/to/unifi-mcp/.venv/bin/python", "-m", "unifi_mcp.server"],
      "enabled": true
    }
  }
}

Verfügbare Tools

Verwaltung mehrerer Geräte

• list_unifi_devices - Alle konfigurierten UniFi-Geräte und ihre Dienste auflisten

Geräteverwaltung

• list_devices - Alle UniFi-Netzwerkgeräte auflisten

• get_device_details - Detaillierte Geräteinformationen abrufen

• restart_device - Ein Gerät neu starten

• locate_device - LED blinken lassen, um ein Gerät zu lokalisieren

• get_device_stats - Leistungsstatistiken abrufen

• upgrade_device - Firmware aktualisieren

• provision_device - Neubereitstellung erzwingen

Client-Verwaltung

• list_clients - Verbundene Clients auflisten

• list_all_clients - Alle bekannten Clients auflisten (einschließlich offline)

• get_client_details - Client-Details abrufen

• block_client / unblock_client - Clients blockieren/entsperren

• kick_client - Einen Client trennen

• forget_client - Aus den bekannten Clients entfernen

• get_client_traffic - Verkehrsstatistiken abrufen

• reserve_client_ip - IP per DHCP-Reservierung reservieren

Site-Verwaltung

• list_sites - Alle Sites auflisten

• get_site_health - Site-Health-Status abrufen

• get_site_settings - Site-Einstellungen abrufen

• get_sysinfo - Systeminformationen abrufen

• get_networks - Netzwerk-/VLAN-Konfigurationen abrufen

• get_wlans - WLAN-Konfigurationen abrufen

• get_port_profiles - Switch-Port-Profile abrufen

• get_firewall_rules - Legacy-Firewall-Regeln abrufen

• get_firewall_policies - Zonenbasierte Firewall-Richtlinien abrufen (UniFi Network 9+)

• get_routing_table - Routing-Tabelle abrufen

• get_port_forwards - Port-Weiterleitungsregeln abrufen

• create_port_forward / delete_port_forward - Port-Weiterleitungen verwalten

Konfigurationsverwaltung (Schreibzugriff)

• create_wlan / update_wlan / delete_wlan - Drahtlose Netzwerke verwalten

• create_firewall_policy / set_firewall_policy_enabled / delete_firewall_policy - Zonenbasierte Firewall-Richtlinien verwalten

• export_camera_clip - Kameraaufzeichnungsclip als MP4 exportieren (Protect)

• get_all_sites_health - Statusübersicht über alle Standorte

Schreib-Tools, die Daten entfernen oder Störungen verursachen, sind durch eine Bestätigungsabfrage abgesichert oder werden über MCP-Annotationen als destruktiv markiert.

Statistik & Überwachung

• get_network_health - Allgemeiner Netzwerkstatus

• get_recent_events - Aktuelle Ereignisse

• get_alarms - Aktive Alarme

• archive_all_alarms - Alle Alarme archivieren

• run_speed_test - Speedtest starten

• get_speed_test_status - Speedtest-Ergebnisse abrufen

• get_dpi_stats - DPI-Statistiken

• get_traffic_summary - Datenverkehrsübersicht

KI-Analysetools

• analyze_network_issues - Umfassende Problemanalyse

• get_optimization_recommendations - Konfigurationsempfehlungen

• get_client_experience_report - Client-Qualitätskennzahlen

• get_device_health_summary - Gerätestatusübersicht

• get_traffic_analysis - Analyse von Datenverkehrsmustern

• get_all_sites_health - Statusübersicht über alle Standorte

Multi-Site-Orchestrierung

• get_global_inventory - Einheitliches Geräteinventar über alle Controller

• get_global_health - Aggregierter Statusbericht über alle Controller

• get_global_client_summary - Client-Anzahl, Top-Talker, blockierte Clients über alle Controller

• troubleshoot_client - Detaillierte Client-Fehlerbehebung

UniFi Protect

• list_cameras - Alle Kameras mit Verbindungsstatus auflisten

• get_camera_details - Detaillierte Kamerainformationen abrufen

• get_camera_snapshot - Live-Schnappschuss abrufen (base64 JPEG)

• get_protect_system_info - NVR-Systeminformationen abrufen

• get_camera_health_summary - Kamerastatusübersicht mit Problemen

• get_liveviews - Konfigurierte Liveview-Layouts abrufen

• get_protect_accessories - Lichter, Sensoren, Klingeln und Viewer auflisten

UniFi Protect-Ereignisse (erfordern Benutzername/Passwort)

• get_motion_events - Aktuelle Bewegungsereignisse abrufen

• get_smart_detections - Ereignisse der intelligenten Erkennung abrufen (Person, Fahrzeug, Tier, Paket)

• get_protect_event_summary - Zusammenfassung aller Ereignisse nach Typ

• get_recent_protect_activity - Schnelle Übersicht über aktuelle Aktivitäten

Beispielkonversationen

Nachdem du den MCP-Server verbunden hast, kannst du Claude fragen:

Netzwerkverwaltung

• "Liste alle meine UniFi-Geräte auf"

• "Wie ist der aktuelle Netzwerkstatus?"

• "Analysiere mein Netzwerk auf Probleme"

• "Welche Optimierungsempfehlungen hast du?"

• "Zeig mir die Kennzahlen zur Client-Erfahrung"

• "Führe eine Fehlerdiagnose für den Client mit der MAC-Adresse aa:bb:cc:dd:ee:ff durch"

• "Welche Clients verbrauchen die meiste Bandbreite?"

• "Gibt es Geräte, die Firmware-Updates benötigen?"

• "Zeig mir die aktuellen Netzwerkereignisse"

• "Führe einen Speedtest durch"

UniFi Protect

• "Liste alle meine Kameras auf"

• "Zeig mir die Kamerastatusübersicht"

• "Hole einen Schnappschuss von der Haustürkamera"

• "Wie ist der Status meines NVR?"

• "Gibt es Kameras, die nicht verbunden sind?"

• "Zeig mir das Protect-Zubehör"

Protect-Ereignisse (Anmeldedaten erforderlich)

• "Zeig mir aktuelle Bewegungsereignisse"

• "Welche intelligenten Erkennungen gab es in den letzten 24 Stunden?"

• "Gab es heute Personenerkennungen?"

• "Gib mir eine Ereigniszusammenfassung für die letzte Woche"

• "Zeig aktuelle Aktivitäten von der Haustürkamera"

Mehrere Geräte

• "Liste meine konfigurierten UniFi-Geräte auf"

• "Zeig die Kameras auf meinem NVR"

• "Hole den Netzwerkstatus vom Haupt-Gateway"

Entwicklung

Tests ausführen

uv run pytest

Code-Formatierung

uv run ruff check .
uv run ruff format .

Docker

docker build -t unifi-mcp .
docker run -i --rm --env-file .env unifi-mcp

Neue Funktionen anfragen

• Neue Skills: Eröffne ein Issue mit dem Präfix [Skill] — beschreibe das Problem, den Workflow und die erwartete Ausgabe

• Skills ändern: Eröffne ein Issue mit dem Präfix [Skill: skill-name] — was fehlt oder nicht funktioniert

• Neue Tools: Eröffne ein Issue mit dem Präfix [Tool] — gib den UniFi-API-Endpunkt und das erwartete Format an

Siehe SKILLS.md für detaillierte Beitragsrichtlinien.

Siehe CHANGELOG.md für die Versionshistorie und CONTRIBUTING.md, um einen Beitrag zu leisten.

Sicherheitshinweise

• Anmeldedaten werden über Umgebungsvariablen übergeben — committe niemals .env

• Die SSL-Überprüfung ist standardmäßig für selbstsignierte Zertifikate deaktiviert

• Der Server stellt nur Leseoperationen und sichere Verwaltungsbefehle bereit

• Destruktive Operationen (Standort löschen, Werksreset) sind nicht verfügbar

• API-Schlüssel sollten sicher aufbewahrt und regelmäßig rotiert werden

Lizenz

MIT License

Mitwirken

Beiträge sind willkommen! Bitte eröffne ein Issue oder reiche einen Pull-Request ein.