Hermes/unifi-network-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
unifi-network-mcp/README.md
T
Hermes 9255f72ddc
build / build (push) Failing after 37s
Details
unifi-network-mcp image: Dockerfile + Gitea Actions build workflow + README
2026-08-17 02:34:21 +00:00

3.3 KiB
Raw Permalink Blame History

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.

Reference in New Issue View Git Blame Copy Permalink