network-mcp

Eigenständiger HTTP-MCP-Server für die Verwaltung des Heimnetzwerks über eine UniFi Dream Machine.

Die aktuelle Controller-Implementierung verwendet die lokale UniFi-Network-UI-/Controller-API, da sie das direkte Client-Blocklist-Verhalten unterstützt, das für die Klartext-Geräteverwaltung benötigt wird. Der Rest der Anwendung hängt von einer kleinen NetworkController-Schnittstelle ab, sodass diese später durch die offizielle UniFi-Network-API ersetzt oder ergänzt werden kann.

Einrichtung

bun install
cp .env.example .env
bun run start

Der Dienst lauscht standardmäßig auf 127.0.0.1:4123.

Docker

Für das gehostete/Heim-Setup führen Sie es mit Docker Compose aus:

cp .env.example .env
docker compose up -d --build

Die Compose-Datei bindet den Dienst innerhalb des Containers an 0.0.0.0, veröffentlicht ihn nur auf dem Host-Loopback unter 127.0.0.1:4123 und speichert LowDB-Daten in ./data.

Nach Codeänderungen neu erstellen/neu starten:

docker compose up -d --build

Logs anzeigen:

docker compose logs -f network-mcp

Logs werden mit Winston als JSON auf stdout ausgegeben. Setzen Sie LOG_LEVEL=debug, um UniFi-Anfragezeiten und MCP-Anfragediagnosen einzuschließen.

Endpunkte

• GET /health

• POST /mcp

• GET /mcp

• DELETE /mcp

Wenn MCP_AUTH_TOKEN gesetzt ist, erfordert /mcp:

Authorization: Bearer <token>

OpenCode-Konfiguration

Fügen Sie einen entfernten MCP-Server zu /home/zac/.config/opencode/opencode.json hinzu:

{
  "mcp": {
    "home-network": {
      "type": "remote",
      "url": "http://127.0.0.1:4123/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:HOME_NETWORK_MCP_TOKEN}"
      }
    }
  }
}

Starten Sie den gehosteten OpenCode-Dienst neu, nachdem Sie die MCP-Konfiguration geändert haben.

Werkzeuge

• list_clients

• find_device

• add_tag

• remove_tag

• list_tags

• add_displayname

• block_device

• unblock_device

• block_by_tag

• unblock_by_tag

• show_blocked

• unblock_all

• recent_actions

MAC-Adressen sind der kanonische Geräteschlüssel. Tags und Anzeigenamen werden lokal in LowDB unter DB_PATH gespeichert.