network-mcp

UniFi Dream Machine を介してホームネットワークを管理するためのスタンドアロン型 HTTP MCP サーバーです。

現在のコントローラ実装は、ローカルの UniFi Network UI/コントローラ API を使用しています。これは、プレーンテキストでのデバイス管理に必要な、クライアントを直接ブロックリストに登録する動作に対応しているためです。アプリケーションの残りの部分は小さな NetworkController インターフェースに依存しているため、後で公式の UniFi Network API に置き換えたり補完したりできます。

セットアップ

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

サービスはデフォルトで 127.0.0.1:4123 で待ち受けます。

Docker

ホスト運用/ホームセットアップでは、Docker Compose で実行します:

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

Compose ファイルはコンテナ内でサービスを 0.0.0.0 にバインドし、ホストのループバック 127.0.0.1:4123 にのみ公開し、LowDB データを ./data に永続化します。

コード変更後は再ビルド/再起動します:

docker compose up -d --build

ログを表示します:

docker compose logs -f network-mcp

ログは Winston により JSON 形式で stdout に出力されます。LOG_LEVEL=debug を設定すると、UniFi リクエストのタイミングと MCP リクエストの診断情報が含まれます。

エンドポイント

• GET /health

• POST /mcp

• GET /mcp

• DELETE /mcp

MCP_AUTH_TOKEN が設定されている場合、/mcp には次が必要です:

Authorization: Bearer <token>

OpenCode 設定

リモート MCP サーバーを /home/zac/.config/opencode/opencode.json に追加します:

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

MCP 設定を変更したら、ホストされている OpenCode サービスを再起動してください。

ツール

• 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 アドレスはデバイスの正規キーです。タグと表示名は、DB_PATH 配下の LowDB にローカル保存されます。