64 lines
3.3 KiB
Markdown
64 lines
3.3 KiB
Markdown
# 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.
|