unifi-network-mcp/README.md

unifi-network-mcp

The UniFi Network MCP server (unifi-network-mcp on PyPI) packaged as a container image, built by Gitea Actions in this repo. Runs the server in streamable-HTTP mode so MCP clients (Hermes Agent) can call it over the network without carrying any controller credentials — UNIFI_HOST / UNIFI_USERNAME / UNIFI_PASSWORD live only in the deployed server's own Kubernetes secret.

• Image: gitea.williammiceli.systems/hermes/unifi-network-mcp
• Consumed by: William/Kubernetes_Cluster0 → cluster0 (Personal)/#active/#applications/ai-0 (Hermes Agent)/ai-0-3 (UniFi MCP)/

Why this server

Two active open-source UniFi MCP servers were evaluated:

	unifi-network-mcp (sirkirby/unifi-mcp) — chosen	unifi-mcp-server (enuno)
Activity	Very active (PyPI release every few days; 116 releases)	Slow (5 releases, last May 2026)
Tools	189 Network tools (stable), 15 categories incl. firewall, clients, devices, stats, VPN	~130 tools across network areas, broader but less mature
Auth model	Local controller login (username/password)	Local API key (UNIFI_API_KEY)
HTTP transport	Native streamable-http + DNS-rebinding protection + Host allowlist	SSE/streamable-http, no caller auth
Safety	Preview-then-confirm for all mutations; policy gates; secret redaction in responses	Standard

Local username/password login matches the UniFi controller's local-account model directly and is the simplest credential Will needs to create (one dedicated local admin/service account). The response redaction (Wi-Fi passphrases, VPN keys, API tokens → ***REDACTED***) keeps controller secrets out of agent context by default.

Updates (fully automatic)

The build workflow (.gitea/workflows/build.yaml) runs:

1. Weekly, Monday 06:00 UTC — resolves the newest published unifi-network-mcp version on PyPI; if no image exists for it yet, builds and pushes v<version> (and latest). This lands ~7 hours before the cluster0 image-update cron (Monday 13:00 UTC), which then bumps the deployment's image tag exactly like any other app.
2. On push to main — e.g. after bumping the Dockerfile's default UNIFI_NETWORK_MCP_VERSION ARG.
3. Manual dispatch — Actions → build → Run workflow, optionally with an explicit version.

Skips automatically when the resolved version is already published. Registry login uses a dedicated scoped PAT (REGISTRY_TOKEN repo Actions secret, write:package) — Gitea's container registry rejects scoped token requests from the Actions job token (upstream issue #23642).

Runtime configuration

Set at deploy time by the Kubernetes manifests (never baked in):

Env	Purpose
UNIFI_HOST	Controller address (required — server refuses to start without it)
UNIFI_USERNAME	Local controller admin/service account (from the server's own secret)
UNIFI_PASSWORD	Password for that account (from the server's own secret)
UNIFI_VERIFY_SSL	false (controller uses a self-signed certificate)
UNIFI_MCP_ALLOWED_HOSTS	Trusted Host/Origin for the server's DNS-rebinding protection

Endpoints: /mcp (streamable HTTP; FastMCP default path). No /health endpoint upstream — Kubernetes probes use tcpSocket.