mcp-unifi

Ein MCP-Server für die Verwaltung von selbst gehosteten UniFi-Gateways. Fünfzehn Tools decken Geräte, Netzwerke/VLANs, WLAN-SSIDs (vollständiges CRUD), Firewall-Regeln (vollständiges CRUD), Switch-Port-Profile und verbundene Clients ab. Zusätzlich gibt es ein create_iot_network-Tool, das in einem einzigen Aufruf ein isoliertes IoT-Subnetz (VLAN, SSID und Firewall-Block) bereitstellt, inklusive automatischem Rollback bei Teilfehlern.

Basiert auf FastMCP mit Streamable HTTP-Transport. Kommuniziert mit einem UCG-Fiber, UDM Pro oder jedem anderen UniFi OS-Gateway über den lokalen API-Schlüssel. Kein Site Manager / Cloud-Konto erforderlich.

Jedes Tool gibt JSON zurück. Fehler werden als strukturiertes {"error": "...", "stub_mode": bool}-Objekt zurückgegeben, sodass die MCP-Schleife bei einem Gateway-Problem nicht abstürzt.

Warum

Die meisten UniFi-Automatisierungen bedeuten heute, sich durch die Controller-UI zu klicken, spröde Einmalskripte zu schreiben oder ein schwergewichtiges Community-SDK einzubinden. mcp-unifi bietet jedem MCP-fähigen Client (Claude Code, Claude Desktop, benutzerdefinierte Agenten) eine kleine, fokussierte und gut typisierte Oberfläche für die Operationen, die Sie tatsächlich jede Woche durchführen: ein IoT-VLAN einrichten, eine Firewall-Regel löschen, SSIDs prüfen, adoptierte Geräte auflisten.

Das zusammengesetzte create_iot_network-Tool verwandelt einen 15-stufigen UI-Workflow in einen einzigen Tool-Aufruf.

Schnellstart

Ziehen Sie das veröffentlichte Image und führen Sie es aus:

docker run --rm \
  -p 3714:3714 \
  -e STUB_MODE=true \
  ghcr.io/pete-builds/mcp-unifi:0.2.0

Der Server startet standardmäßig im Stub-Modus, der realistische Mock-Daten zurückgibt und keine UniFi-Hardware erfordert. Registrieren Sie ihn bei Claude Code:

claude mcp add unifi --transport http --scope user --url http://localhost:3714/mcp

Bitten Sie Claude Code dann, "list my UniFi devices" auszuführen, und Sie sollten zwei Stub-Geräte sehen.

Um mit einem echten Gateway zu kommunizieren, übergeben Sie die Anmeldedaten und deaktivieren Sie den Stub-Modus:

docker run --rm \
  -p 3714:3714 \
  -e STUB_MODE=false \
  -e UNIFI_HOST=192.168.1.1 \
  -e UNIFI_API_KEY=<your-local-api-key> \
  ghcr.io/pete-builds/mcp-unifi:0.2.0

Generieren Sie den API-Schlüssel unter Einstellungen → Control Plane → Integrationen auf dem Gateway.

Tool-Referenz

Jedes Tool gibt einen JSON-String zurück. Fehler werden als strukturiertes {"error": "...", "stub_mode": bool}-Objekt zurückgegeben, damit Claude den Fehler darstellen kann, ohne die MCP-Schleife zum Absturz zu bringen.

Stub-Modus vs. Real-Modus

Der Wechsel der Modi ist eine Konfigurationsänderung, keine Codeänderung. Dieselben elf Tools, dieselben Antwortformate.

Konfiguration

Die gesamte Konfiguration wird aus Umgebungsvariablen (und einer .env-Datei, falls vorhanden) gelesen. Die Konfiguration wird beim Start durch Pydantic validiert; ungültige Werte führen zu einem sofortigen Abbruch mit einer hilfreichen Meldung.

Ein vollständiges Beispiel finden Sie in .env.example.

MCP-Client-Einrichtung

Claude Code

claude mcp add unifi --transport http --scope user --url http://<host>:3714/mcp

Claude Desktop

Fügen Sie Folgendes zu Ihrer claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "unifi": {
      "transport": "streamable-http",
      "url": "http://<host>:3714/mcp"
    }
  }
}

Generische Konfiguration

Streamable HTTP unter http://<host>:3714/mcp. Jeder MCP-Client, der den Streamable HTTP-Transport unterstützt (Spezifikation 2025-03-26+), kann eine Verbindung herstellen.

Architektur

+---------------------+         Streamable HTTP         +---------------------+
|  MCP Client         |  -------------------------->    |  mcp-unifi          |
|  (Claude Code, etc) |  <--------------------------    |  (FastMCP server)   |
+---------------------+                                 +----------+----------+
                                                                   |
                                                                   |  HTTPS + X-API-Key
                                                                   v
                                                        +----------+----------+
                                                        |  UniFi OS Gateway   |
                                                        |  /proxy/network/... |
                                                        +---------------------+

Der Server ist ein schlanker asynchroner Proxy: Er übersetzt MCP-Tool-Aufrufe in UniFi-Controller-REST-Aufrufe, formatiert die Antworten und gibt JSON zurück. Er speichert keinen Zustand, ruft keine Cloud-Dienste auf und authentifiziert keine eingehenden MCP-Verbindungen (führen Sie ihn in einem vertrauenswürdigen LAN aus).

Sicherheitshinweise

• Der UNIFI_API_KEY befindet sich nur in der Umgebung des Containers. Er wird niemals protokolliert, niemals in MCP-Antworten zurückgegeben und niemals von diesem Server auf die Festplatte geschrieben.

• WLAN-Passwörter werden bei jeder Tool-Antwort bereinigt ([REDACTED]), selbst im Stub-Modus.

• Der Container läuft als UID 1000, ohne Shell, ohne Home-Verzeichnis, mit einem schreibgeschützten Root-Dateisystem (/tmp ist tmpfs) und no-new-privileges.

• Das Basis-Image ist per Digest fixiert. Python-Abhängigkeiten werden mit pip --require-hashes aus einer hash-gesperrten requirements.lock installiert.

• Das veröffentlichte Image ist Multi-Arch (amd64/arm64) mit Build-Provenienz-Attestierung und SBOM via docker/build-push-action.

• Der MCP-Server selbst ist nicht authentifiziert. Platzieren Sie ihn hinter einer vertrauenswürdigen LAN-Grenze, einem Reverse-Proxy mit Authentifizierung oder einer Tailscale-ACL.

Für Schwachstellenberichte siehe SECURITY.md.

Entwicklung

Erfordert Python 3.13+ und Docker.

# Clone + install dev deps
git clone https://github.com/pete-builds/mcp-unifi.git
cd mcp-unifi
python -m venv .venv && source .venv/bin/activate
pip install --require-hashes -r requirements-dev.lock
pip install -e . --no-deps

# Run the test suite (101 tests, ~95% coverage)
pytest

# Lint and format
ruff check src tests
ruff format src tests

# Type check (mypy strict)
mypy src/mcp_unifi

# Run the server locally in stub mode
python -m mcp_unifi.server

# Or build the image yourself instead of pulling from GHCR
cp docker-compose.example.yml docker-compose.yml
docker compose up --build

Tests

======================= 101 passed in 1.5s =======================

Name                          Stmts  Miss  Branch  BrPart  Cover
-----------------------------------------------------------------
src/mcp_unifi/__init__.py         2     0       0       0   100%
src/mcp_unifi/clients/__init__    3     0       0       0   100%
src/mcp_unifi/clients/stubs.py   70     1       6       0    99%
src/mcp_unifi/clients/unifi.py   82     0      12       0   100%
src/mcp_unifi/config.py          38     1       8       0    98%
src/mcp_unifi/healthcheck.py     18     1       0       0    94%
src/mcp_unifi/logging_setup.py   33     1      12       2    93%
src/mcp_unifi/models.py           6     0       0       0   100%
src/mcp_unifi/server.py         232    15      70       5    92%
-----------------------------------------------------------------
TOTAL                           484    19     108       7    95%

CI-Gates bei mindestens 80% Abdeckung, ruff lint, ruff format, mypy strict und ein Trivy fs+image Scan, der bei jedem HIGH- oder CRITICAL-Fund fehlschlägt.

Abhängigkeiten aktualisieren

Die Dateien requirements.lock und requirements-dev.lock sind hash-fixiert. Bearbeiten Sie requirements.in (oder requirements-dev.in) und generieren Sie sie dann neu:

uv pip compile requirements.in --output-file requirements.lock --generate-hashes --python-version 3.13
uv pip compile requirements-dev.in --output-file requirements-dev.lock --generate-hashes --python-version 3.13

Dependabot öffnet wöchentlich PRs für Updates auf requirements.in-Ebene und für den Docker-Basis-Image-Digest.

Danksagungen

Die Endpunktpfade des UniFi-Controllers wurden mit dem Projekt sirkirby/unifi-mcp abgeglichen. Dieses Repository wurde als Recherchematerial für die API-Oberfläche verwendet; es wurde kein Code kopiert. Die Implementierung hier ist ein unabhängiger FastMCP + httpx-Build, der dem bewährten Forge-Muster folgt.

Lizenz

MIT.

Mitwirken

Issues und Pull Requests sind willkommen. Vor dem Öffnen eines PR:

1. Stellen Sie sicher, dass ruff check, ruff format --check und mypy src/mcp_unifi sauber sind.

2. Fügen Sie Tests hinzu oder aktualisieren Sie diese, halten Sie die Abdeckung bei 80% oder höher.

3. Führen Sie pytest lokal aus und bestätigen Sie, dass die Suite besteht.

4. Aktualisieren Sie CHANGELOG.md unter einer [Unreleased]-Überschrift.