UniFi MCP Server
by Sliking
README.md
# UniFi MCP Server
[](https://deploy.workers.cloudflare.com/?url=https://github.com/Sliking/unifi-mcp-server)
[](https://github.com/Sliking/unifi-mcp-server/actions/workflows/ci.yml)
A secure, **read-only** remote [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for UniFi networks, running on **Cloudflare Workers**.
Connect it to any MCP-capable assistant (Claude, ChatGPT, Perplexity, Cursor, VS Code, …) and ask things like:
- *"Audit my current firewall policies and identify security issues"*
- *"Show me all VLANs and which ones can communicate"*
- *"Which devices are generating the most traffic?"*
- *"Is my IoT network properly isolated?"*
```
┌──────────────┐ OAuth 2.1 + Streamable HTTP ┌─────────────────────────┐ Workers VPC ┌─────────────┐ LAN ┌──────────────┐
│ Chat assistant├──────────────────────────────►│ Cloudflare Worker (MCP) ├─────────────────►│ cloudflared ├─────────►│ UniFi console │
│ (MCP client) │ Bearer token (audience-bound)│ read-only UniFi client │ (private, no │ (tunnel) │ HTTPS │ UDM / UCG / … │
└──────────────┘ └─────────────────────────┘ public host) └─────────────┘ └──────────────┘
│ sign-in
▼
GitHub OAuth (allow-listed users only)
```
## Features
| Tool | What it does |
| --- | --- |
| `unifi_audit_security` | Prioritised findings (critical → info) with remediation: Internet-exposed rules/port forwards, any-any allows, shadowed and dangling rules, inter-VLAN segmentation gaps, IoT/guest leakage, Wi-Fi encryption (WEP/open/WPA2-only/PMF), UPnP, IPS, device SSH, firmware. |
| `unifi_vlan_connectivity` | Who-can-talk-to-whom matrix for every routed VLAN pair, the rule/policy that decides it, and any port-level exceptions. Supports both the **zone-based firewall** (Network 9+) and **legacy** LAN_IN/GUEST_IN rules. |
| `unifi_check_iot_isolation` | Pass/warn/fail checks for each IoT network, plus IoT-looking devices (by vendor/hostname) that are sitting on trusted networks. |
| `unifi_top_talkers` | Clients ranked by session traffic or by current throughput. |
| `unifi_network_overview` | Health of WAN/LAN/WLAN/VPN, device and client counts, networks. |
| `unifi_list_networks`, `unifi_list_firewall`, `unifi_list_clients`, `unifi_list_devices`, `unifi_list_wifi`, `unifi_list_sites` | Inventory, with all secrets redacted. |
It also ships MCP **prompts** for the four example questions above.
### Two ways to connect
- **Local mode** (recommended): Workers VPC + Cloudflare Tunnel with a View-Only local API key. Full feature set.
- **Cloud mode**: through Ubiquiti's Site Manager connector (`api.ui.com`) with no tunnel or extra hardware. Port-forward, UPnP and IPS checks and per-client traffic are not available because Ubiquiti's public API does not expose them. See the [comparison](docs/DEPLOYMENT.md).
## Security model
This server touches home network equipment, so it is built to be safe by default:
- **Read-only by construction.** The UniFi client can only issue `GET` requests to an explicit allow-list of endpoints. There is no code path that can change your network.
- **Standards-based authentication.** OAuth 2.1 authorization server with PKCE S256 ([RFC 7636](https://www.rfc-editor.org/rfc/rfc7636)), Authorization Server Metadata ([RFC 8414](https://www.rfc-editor.org/rfc/rfc8414)), Dynamic Client Registration ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)), Protected Resource Metadata ([RFC 9728](https://www.rfc-editor.org/rfc/rfc9728)), Resource Indicators / audience-bound tokens ([RFC 8707](https://www.rfc-editor.org/rfc/rfc8707)), `iss` in authorization responses ([RFC 9207](https://www.rfc-editor.org/rfc/rfc9207)) and Bearer tokens ([RFC 6750](https://www.rfc-editor.org/rfc/rfc6750)), as required by the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization).
- **Deny by default.** Users sign in with GitHub, and only logins listed in `ALLOWED_GITHUB_USERS` are authorised. The allow-list is re-checked on every MCP request, so removing a user revokes access immediately. The GitHub token is revoked right after sign-in and never stored.
- **No inbound ports on your network.** In local mode, the Worker reaches your console through [Workers VPC](https://developers.cloudflare.com/workers-vpc/) and an outbound-only Cloudflare Tunnel. The VPC service is pinned to a single host and port, which prevents SSRF. A Cloudflare Access service-token mode is also supported. In cloud mode, it goes through Ubiquiti's own cloud connector over HTTPS, using an allow-list of read-only Integration API paths.
- **Secrets never leave the Worker.** Wi-Fi passphrases, RADIUS secrets, VPN keys and SSH passwords are redacted from every response before it reaches the LLM.
- **Defence in depth.** Short-lived access tokens (1 h) with refresh-token rotation, per-user rate limiting, DNS-rebinding (Host) protection, CSRF-protected consent screen, `__Host-` cookies, strict security headers, request timeouts and response-size limits, and a structured audit log of every tool call in Workers Observability.
See [SECURITY.md](SECURITY.md) for the threat model and how to report vulnerabilities.
## Requirements
- A UniFi OS console (UDM, UDM Pro/SE, UCG Ultra/Max, UDR, UX, Cloud Key Gen2+, or UniFi OS Server) running UniFi Network 8.x or newer. Zone-based firewall analysis requires Network 9.0+.
- A Cloudflare account (the Workers Free plan is enough).
- A machine on your LAN that can run `cloudflared` (Raspberry Pi, NAS, Docker host, …).
- A GitHub account for sign-in.
## Quick start (one-click, cloud mode, about 10 minutes)
You need a Cloudflare account (the Free plan is fine), a GitHub account, and a UniFi console on UniFi OS 5.0.3+ that you can see at [unifi.ui.com](https://unifi.ui.com).
1. **Find your Worker URL.** In the Cloudflare dashboard, go to **Workers & Pages** and note your `*.workers.dev` subdomain. Your server will be at `https://unifi-mcp-server.<subdomain>.workers.dev`.
2. **Create a GitHub OAuth app** at <https://github.com/settings/applications/new>:
- Homepage URL: `https://unifi-mcp-server.<subdomain>.workers.dev`
- Redirect URI: `https://unifi-mcp-server.<subdomain>.workers.dev/callback`
- Leave wildcard matching and device flow unchecked. Generate a client secret.
3. **Create a UniFi API key** at [unifi.ui.com](https://unifi.ui.com) → **API** → **Create API Key**.
4. **Click _Deploy to Cloudflare_** above and fill in the prompts:
- `UNIFI_API_KEY`: the key from step 3
- `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`: from step 2
- `COOKIE_ENCRYPTION_KEY`: the output of `openssl rand -hex 32`
5. **Authorise yourself.** In the dashboard, go to **Workers & Pages → unifi-mcp-server → Settings → Variables and Secrets**. Set `ALLOWED_GITHUB_USERS` to your GitHub login. It is empty by default, so nobody can sign in until you set it. If you own more than one UniFi console, also set `UNIFI_CONSOLE_ID`, the long ID in the `unifi.ui.com/consoles/<ID>/…` URL.
6. **Connect your assistant** to `https://unifi-mcp-server.<subdomain>.workers.dev/mcp` (see below) and sign in with GitHub.
If you deploy under a different Worker name, use that name in the URLs above.
For the full feature set (port forwards, UPnP/IPS checks, per-client traffic), use **local mode** with Cloudflare Tunnel and a View-Only local API key. See **[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)**.
### Manual deploy (CLI)
```bash
git clone https://github.com/Sliking/unifi-mcp-server.git && cd unifi-mcp-server
npm install
npx wrangler login
# edit "vars" in wrangler.jsonc (ALLOWED_GITHUB_USERS, UNIFI_MODE, UNIFI_CONSOLE_ID)
npx wrangler secret put UNIFI_API_KEY
npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
openssl rand -hex 32 | npx wrangler secret put COOKIE_ENCRYPTION_KEY
npm run deploy # the OAuth KV namespace is created automatically
```
## Connecting clients
| Client | How |
| --- | --- |
| **Claude** (web/desktop) | Settings → Connectors → *Add custom connector* → URL `https://…/mcp`. |
| **ChatGPT** | Settings → Apps & Connectors → *Advanced* → enable Developer mode → *Create* connector → URL `https://…/mcp`, authentication *OAuth*. |
| **Perplexity** | Settings → Connectors → *Add connector* → Remote MCP → URL `https://…/mcp`. |
| **Claude Code** | `claude mcp add --transport http unifi https://…/mcp` |
| **Cursor / VS Code** | Add `{"url": "https://…/mcp"}` to the MCP server config. |
| **MCP Inspector** | `npx @modelcontextprotocol/inspector` → Streamable HTTP → `https://…/mcp`. |
The first connection opens a browser window: approve the client, sign in with GitHub, done.
## Development
```bash
npm install
cp .dev.vars.example .dev.vars # fill in values
npm run dev # http://localhost:8788/mcp
npm run check # type-check + unit tests
```
Analysis logic (`src/analysis/`) is pure TypeScript and fully unit-tested with fixtures in `test/fixtures.ts`, so you can contribute new checks without UniFi hardware.
## Project layout
```
src/
index.ts OAuth provider + MCP endpoint wiring, allow-list, rate limiting
auth/ GitHub sign-in, consent screen, CSRF/state helpers
mcp/server.ts MCP tools and prompts
unifi/client.ts Read-only, allow-listed UniFi API client
unifi/redact.ts Secret redaction
analysis/ Connectivity engine, security audit, IoT checks, traffic ranking
test/ Vitest unit and protocol tests
docs/ Deployment and architecture docs
```
## Contributing
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md). Good first contributions: new audit checks, support for more UniFi endpoints, and real-world (anonymised) fixtures from different UniFi Network versions.
## Disclaimer
Not affiliated with or endorsed by Ubiquiti Inc. "UniFi" is a trademark of Ubiquiti Inc. The analysis is heuristic and based on configuration only; always verify findings before acting on them.
## License
[MIT](LICENSE)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues