unifi-safe-mcp
# UniFi Safe MCP
A focused, read-only UniFi Network MCP server providing bounded health, device, and active-client views. Extracted from `spectrenet-mcp` commit `2e63f009d8f4642e17398685baef0251811d6637`; this repository is self-contained.
## Safety contract
- Exactly three read tools: `network_health`, `devices`, and `clients`; no configuration, command, adoption, restart, block, or other mutation tools.
- Appliance data requests use HTTP `GET` only (authentication necessarily uses `POST /api/auth/login`).
- TLS certificate and hostname verification are enabled by default.
- Authentication and appliance data redirects are rejected rather than followed.
- The configured site is encoded as one URL path segment, and endpoint suffixes are closed-allowlisted.
- HTTP response bytes, returned list lengths, projected fields, and audit fields are bounded.
- Credentials and full responses are not audited.
## Compatibility
This targets the UniFi OS console proxy paths `/api/auth/login` and `/proxy/network/api/s/{site}/...`, observed on modern UniFi OS appliances. Older self-hosted UniFi Network Controllers commonly use `/api/login` and non-proxied `/api/s/...`; those are **not supported**. Ubiquiti changes private/internal endpoints between appliance and Network Application versions. No version matrix is certified: test this alpha against your exact console firmware and Network Application version in non-production, and pin upgrades operationally.
## Install and run
```sh
uv sync --extra test
uv run unifi-safe-mcp --help
uv run unifi-safe-mcp
```
The server uses MCP stdio and does not load `.env`. Treat `.env.example` as fake documentation only; inject a dedicated read-only account through a supervisor/secret manager.
## Verify
```sh
uv sync --locked --extra test
uv run --locked pytest
uv run --locked python -m compileall -q src tests
uv build
```
See [architecture](docs/ARCHITECTURE.md), [compatibility](docs/COMPATIBILITY.md), and [security](docs/SECURITY.md). MIT © 2026 Ben Gauger.
TDQS
Scored across 3 tools
The three tools—network_health, devices, and clients—each address a distinct aspect of a UniFi network with no overlap in purpose. An agent can easily differentiate between them based on their names.
All three tool names are single nouns following a consistent pattern (no verbs or mixed conventions). While this differs from the common verb_noun style, the naming is internally consistent and predictable.
With only three tools, the server is minimal but within the acceptable range for a focused network management utility. The count feels proportionate to the narrow scope of health, device, and client visibility.
The server covers only basic read‑only operations for network health, devices, and clients. It lacks essential UniFi features such as site management, configuration changes, or traffic monitoring, leaving significant gaps for most real‑world use cases.