network-mcp

Standalone HTTP MCP server for home network management through a UniFi Dream Machine.

The current controller implementation uses the local UniFi Network UI/controller API because it supports the direct client blocklist behavior needed for plain-text device management. The rest of the application depends on a small NetworkController interface so this can be replaced or supplemented by the official UniFi Network API later.

Setup

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

The service listens on 127.0.0.1:4123 by default.

Docker

For the hosted/home setup, run it with Docker Compose:

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

The compose file binds the service to 0.0.0.0 inside the container, publishes it only on host loopback at 127.0.0.1:4123, and persists LowDB data in ./data.

Rebuild/restart after code changes:

docker compose up -d --build

View logs:

docker compose logs -f network-mcp

Logs are emitted as JSON to stdout with Winston. Set LOG_LEVEL=debug to include UniFi request timing and MCP request diagnostics.

Endpoints

• GET /health
• POST /mcp
• GET /mcp
• DELETE /mcp

If MCP_AUTH_TOKEN is set, /mcp requires:

Authorization: Bearer <token>

OpenCode Config

Add a remote MCP server to /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}"
      }
    }
  }
}

Restart the hosted OpenCode service after changing MCP config.

Tools

• 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 addresses are the canonical device key. Tags and display names are stored locally in LowDB under DB_PATH.