A Cloudflare Worker that enables cloud agents to access locally-hosted UniFi MCP servers via a secure relay gateway.

Cloud agents communicate with your local UniFi MCP server through a two-leg relay:

Cloud Agent (Claude, n8n, etc.)
        |  HTTPS POST /mcp  (Bearer AGENT_TOKEN)
        v
Cloudflare Worker  ──────────────────────────────────  Durable Object (RelayObject)
                                                                |
                                              WebSocket (WSS) /ws  (relay_token)
                                                                |
                                                   unifi-mcp-relay (local network)
                                                                |
                                                    UniFi MCP Server (stdio/HTTP)

The Durable Object persists location registrations in SQLite and maintains live WebSocket connections to one or more relay clients. When a tool call arrives from a cloud agent, the worker routes it to the appropriate relay client and streams the result back.

Multi-location support: Multiple relay clients can connect simultaneously, each representing a different physical location (home lab, branch office, customer site). Read-only tool calls are automatically fanned out to all connected locations and results are aggregated. Write operations require an explicit __location argument to target a specific site — useful for MSP workflows.

curl -fsSL https://raw.githubusercontent.com/sirkirby/unifi-mcp-worker/main/install.sh | bash

Or install the CLI directly:

npm install -g unifi-mcp-worker
unifi-mcp-worker install

The CLI will:

1. Check prerequisites (Node.js, Wrangler)
2. Deploy the worker to your Cloudflare account
3. Generate and set authentication tokens
4. Display your tokens and next steps

unifi-mcp-worker upgrade

unifi-mcp-worker add-location

unifi-mcp-worker rotate-tokens
unifi-mcp-worker status

unifi-mcp-worker destroy

Secrets are set automatically by the CLI and can be rotated with unifi-mcp-worker rotate-tokens.

Variables are set in wrangler.toml under [vars] or overridden via the Cloudflare dashboard.

The /mcp endpoint accepts standard MCP JSON-RPC requests:

curl -X POST https://your-worker.workers.dev/mcp \
  -H "Authorization: Bearer <agent-token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

The relay always exposes three meta-tools regardless of registration mode:

The CLI manages tokens automatically during install and rotate-tokens. You can also manage tokens manually via the admin API:

curl -X POST https://your-worker.workers.dev/api/locations/token \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"location_name": "Home Lab"}'

Response:

{
  "location_id": "a1b2c3d4-...",
  "location_name": "Home Lab",
  "token": "<relay-token>"
}

Store the token value securely — it is only returned once. Provide it to unifi-mcp-relay as UNIFI_MCP_RELAY_TOKEN (see unifi-mcp for relay client configuration).

unifi-mcp-worker status

Or via the admin API:

curl https://your-worker.workers.dev/api/locations \
  -H "Authorization: Bearer <admin-token>"

Response includes connected: true/false indicating whether the relay client WebSocket is currently active.

Point any MCP-compatible client at the worker URL:

• Endpoint: https://your-worker.workers.dev/mcp
• Auth: Authorization: Bearer <agent-token>
• Transport: HTTP POST (standard MCP JSON-RPC)

Compatible clients include Claude connectors, ChatGPT plugins, n8n MCP nodes, and any platform that supports the MCP protocol over HTTP.

When multiple relay clients are connected, write operations require a __location argument passed to unifi_execute:

{
  "tool_name": "block_client",
  "arguments": { "mac": "aa:bb:cc:dd:ee:ff" },
  "__location": "a1b2c3d4-..."
}

Read-only operations (tools with readOnlyHint: true) are automatically fanned out to all connected locations and results are returned as an aggregated response.

• Timing-safe token comparison — all token validation uses constant-time comparison to prevent timing attacks
• SHA-256 hashed storage — relay tokens are stored as hashes in SQLite; the plaintext is never persisted
• Per-location isolation — each relay client is identified by its own relay token and location ID; locations cannot access each other's data
• HTTPS/WSS transport — all traffic is encrypted in transit; Cloudflare terminates TLS at the edge
• No credentials in config — tokens and secrets are managed via the CLI or wrangler secret put, never committed to source

• unifi-mcp — UniFi MCP server and unifi-mcp-relay client that connects to this relay worker