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 中。