# unifi-network-mcp

The [UniFi Network MCP server](https://github.com/sirkirby/unifi-mcp)
(`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.