UniFi MCP

A Model Context Protocol server for UniFi Network and UniFi Protect, so an AI assistant can answer questions about your network and — if you allow it — act on it.

It talks directly to your UniFi OS console (UDR, UDM/UDM-Pro/SE, UCG, Cloud Key) over your local network. No cloud service, no Ubiquiti account, nothing leaves your LAN except what you choose to share with your assistant.

Works with any MCP client. Ships as a one-click .mcpb plugin for Claude Desktop, as an npx-runnable server, and as a plain Node project.

---

What you can ask

Which devices are on my WiFi right now, and which access point are they on? Is anything on the network having a bad connection? Show me the doorbell events from last night. Take a snapshot from the front door camera. Which ports are forwarded from the internet? Restart the access point in the living room. (needs actions enabled)

Highlights

• Network: devices, clients (live and historical), WiFi networks, VLANs and subnets, firewall rules, port forwards, site health and WAN status, event log, alarms, historical statistics, guest vouchers.
• Protect: cameras and doorbells, live snapshots returned as images, motion/ring/smart-detection events, sensors, lights, chimes, RTSPS stream URLs.
• Three permission tiers — read-only by default; actions and configuration changes are opt-in toggles.
• Two authentication methods — official API key and/or a local admin account, each unlocking a different part of the UniFi API. Use both for full coverage.
• Compact output — every list tool summarises by default (detail: "full" returns the raw UniFi objects) so responses stay readable and cheap.
• Escape hatch — unifi_raw_request reaches any endpoint that has no dedicated tool.

---

Requirements

• A UniFi OS console reachable from the machine running the MCP server.
• Node.js 20.18.1 or newer (only for the npx / source install — the .mcpb plugin uses the runtime that ships with Claude Desktop).
• Credentials, see Authentication.

---

Install

Option A — Claude Desktop plugin (.mcpb)

1. Download unifi-mcp-<version>.mcpb from the latest release.
2. Open Claude Desktop → Settings → Extensions and drag the file in (or double-click it).
3. Fill in the console address and credentials in the settings panel, and decide whether to allow actions.

Everything is bundled, so no separate Node installation is needed.

The npx examples below use the published npm package. Until the first npm release you can point npx straight at the repository instead: npx -y github:mbgroen/unifi-mcp.

Option B — Claude Code

claude mcp add unifi \
  --env UNIFI_HOST=192.168.1.1 \
  --env UNIFI_USERNAME=mcp-readonly \
  --env UNIFI_PASSWORD='your-password' \
  --env UNIFI_API_KEY='your-api-key' \
  -- npx -y @mbgroen/unifi-mcp

Option C — any other MCP client

Add this to the client's MCP server configuration (Cursor, VS Code, Windsurf, Zed, custom hosts):

{
  "mcpServers": {
    "unifi": {
      "command": "npx",
      "args": ["-y", "@mbgroen/unifi-mcp"],
      "env": {
        "UNIFI_HOST": "192.168.1.1",
        "UNIFI_API_KEY": "your-api-key",
        "UNIFI_USERNAME": "mcp-readonly",
        "UNIFI_PASSWORD": "your-password",
        "UNIFI_PERMISSION_MODE": "read-only"
      }
    }
  }
}

Option D — from source

git clone https://github.com/mbgroen/unifi-mcp.git
cd unifi-mcp
npm install
npm run build
cp .env.example .env   # fill it in
node dist/index.js     # speaks MCP over stdio

---

Authentication

UniFi OS exposes two API families, and they are not interchangeable. This server supports both and picks whichever is configured — setting up both gives the widest coverage.

	API key	Local account
Where	Settings → Control Plane → Integrations → Create API Key	Settings → Admins → Add admin (local access only, no 2FA)
Variable	UNIFI_API_KEY	UNIFI_USERNAME + UNIFI_PASSWORD
Covers	Officially supported subset: sites, devices, clients, vouchers, Protect cameras/snapshots	Everything the UniFi web app itself uses: statistics, events, alarms, firewall, port forwards, WLAN/VLAN config, Protect event log
Stability	Stable, documented	Unofficial; may change with a UniFi update

For a read-only setup, create a dedicated local admin with the Viewer role. Actions and configuration changes need an account with admin rights.

Two-factor authentication is not supported for the local account — the session login has no way to prompt for a code. Create a separate local account without 2FA for this server. (Your own account keeps its 2FA.)

---

Permission tiers

The server refuses to expose tools it is not allowed to run — a disallowed tool is not just blocked at call time, it is never listed.

Mode	UNIFI_PERMISSION_MODE	Plugin toggles	What it adds
Read-only (default)	read-only	both off	Reading only. Nothing on your network can change.
Actions	safe	Allow actions	Block/unblock a client, reconnect a client, restart a device, flash its LED, power-cycle a PoE port, toggle an SSID, run a speed test, manage guest vouchers, rename clients, set the doorbell message. All reversible.
Full control	full	Allow configuration changes	Firewall rules, port forwards, WiFi and network settings, firmware upgrades, Protect recording modes, and write access through unifi_raw_request.

Start at read-only. Raise it only when you want the assistant to actually change something, and remember that an assistant acts on what it reads — including device names and notes that come from the network itself.

---

Tools

Read-only

Tool	What it does
Console
unifi_status	Check the connection to the UniFi console: which credentials work, which applications are reachable, and what this server is currently allowed to do. Use this first when something fails.
unifi_raw_request	Escape hatch for endpoints without a dedicated tool. GET is available in every permission mode; other methods require full control. Paths are relative to the chosen API surface.
UniFi Network
unifi_list_sites	List the UniFi Network sites on this console, with the site name to pass to other tools.
unifi_list_devices	List adopted UniFi devices (gateway/router, access points, switches) with model, state, firmware, uptime, client count and load.
unifi_get_device	Full details for one UniFi device by MAC address, including radios, ports, temperatures and uplink.
unifi_list_clients	List clients on the network with IP, signal, throughput and which access point or switch port they use.
unifi_list_known_clients	List all clients the controller has ever seen, including offline ones, their fixed IPs, notes and blocked state.
unifi_list_wlans	List the configured SSIDs with security settings, band and enabled state.
unifi_list_networks	List LANs, VLANs and WAN configuration including subnets and DHCP ranges.
unifi_list_port_forwards	List port forwarding rules on the gateway.
unifi_list_firewall_rules	List firewall rules (and optionally firewall groups) configured on the gateway.
unifi_site_health	Overall health per subsystem (WAN, LAN, WLAN, VPN): status, uptime, latency, throughput and last speedtest result.
unifi_list_events	Recent Network events: client connect/disconnect, roaming, device restarts, configuration changes.
unifi_list_alarms	Open (or archived) alarms raised by the Network application.
unifi_get_stats	Time series statistics for the site, an access point, the gateway or a single client (throughput, clients, latency).
unifi_list_vouchers	List guest hotspot vouchers with their duration, quota and usage.
UniFi Protect
unifi_protect_info	Version, storage and recording status of the UniFi Protect NVR running on this console.
unifi_protect_list_cameras	List cameras and doorbells with connection state, recording mode, battery level and last motion/ring.
unifi_protect_get_camera	Full details of one camera or doorbell, including its feature flags and settings.
unifi_protect_snapshot	Fetch a current still image from a camera or doorbell and return it as an image so it can be looked at directly.
unifi_protect_list_events	Recent Protect events: motion, smart detections (person, vehicle, package), doorbell rings and device connect/disconnect.
unifi_protect_list_devices	List Protect sensors, lights, chimes, viewers and doorlocks.
unifi_protect_get_stream_url	Return the RTSPS URL for a camera so it can be opened in VLC, ffmpeg or a media player.

Actions (safe)

Tool	What it does
UniFi Network
unifi_block_client	Block a device from the network, or lift an existing block. Fully reversible with the same tool.
unifi_reconnect_client	Force a wireless client to reconnect (kick). Useful to push a device to another band or access point.
unifi_authorize_guest	Authorize a client on the guest portal for a period of time, or revoke that access.
unifi_set_client_name	Give a client a friendly name and/or a note in the controller.
unifi_restart_device	Restart an access point, switch or the gateway itself. A soft restart reboots the software; hard power-cycles.
unifi_locate_device	Make a UniFi device flash its LED so you can find it physically, or stop flashing.
unifi_power_cycle_port	Power-cycle a PoE switch port, restarting whatever is plugged into it.
unifi_set_wlan_enabled	Turn an SSID on or off, for example a guest or IoT network.
unifi_run_speedtest	Start a speed test on the gateway, or read the status of the running test.
unifi_create_voucher	Create one or more guest hotspot vouchers.
unifi_revoke_voucher	Delete a guest voucher so it can no longer be used.
UniFi Protect
unifi_protect_set_doorbell_message	Show a custom message on a UniFi doorbell's screen, or reset it to the default. Reversible.
unifi_protect_set_light	Force a UniFi Protect floodlight on or off, or hand control back to motion detection.

Configuration (full)

Tool	What it does
UniFi Network
unifi_set_port_forward_enabled	Turn an existing port forwarding rule on or off.
unifi_set_firewall_rule_enabled	Turn an existing firewall rule on or off.
unifi_update_wlan	Patch settings on an SSID (name, password, band, guest policy, ...). Only the supplied keys change.
unifi_update_network	Patch settings on a LAN/VLAN/WAN definition. Only the supplied keys change.
unifi_upgrade_device	Start a firmware upgrade on a UniFi device. The device reboots when it finishes.
UniFi Protect
unifi_protect_set_recording_mode	Set when a camera records: always, only on detections, or never. This affects your security footage.
unifi_protect_update_device	Patch arbitrary settings on a Protect device (camera, sensor, light, chime, viewer). Only the supplied keys change.

Every list tool accepts detail: "summary" | "full"; site-scoped tools accept site to override the configured site.

---

Configuration reference

Variable	Default	Description
UNIFI_HOST	(required)	Hostname or IP of the console. https:// is assumed.
UNIFI_API_KEY	—	API key for the official Integration API.
UNIFI_USERNAME / UNIFI_PASSWORD	—	Local UniFi OS account for the internal API.
UNIFI_MFA_TOKEN	—	One-time 2FA code, if you really must use an account that has it.
UNIFI_SITE	default	Network site name.
UNIFI_PERMISSION_MODE	read-only	read-only, safe or full.
UNIFI_ALLOW_WRITE	false	Boolean alternative that maps to safe.
UNIFI_ALLOW_FULL_CONTROL	false	Boolean alternative that maps to full.
UNIFI_ENABLE_NETWORK	true	Expose the Network tools.
UNIFI_ENABLE_PROTECT	true	Expose the Protect tools.
UNIFI_VERIFY_TLS	false	Verify the console's certificate. Consoles use a self-signed certificate on their local address.
UNIFI_TIMEOUT_MS	20000	Per-request timeout.

At least one credential set is required; the server exits with an explanation if none is configured.

---

Security notes

• Credentials live in your MCP client's configuration. In Claude Desktop the plugin stores the API key and password in the OS keychain because they are marked sensitive.
• TLS verification is off by default because UniFi consoles present a self-signed certificate for their LAN address. The connection is still encrypted, but it is not authenticated — keep the server on a network you trust, or install a proper certificate and set UNIFI_VERIFY_TLS=true.
• Everything an assistant reads from your network (client names, notes, SSIDs, event messages) is untrusted input. That is one more reason to leave the server read-only unless you have a reason not to.
• Nothing is sent anywhere except to your console and to whatever MCP client you connected.

---

Troubleshooting

Run unifi_status first — it reports which credentials authenticated, which applications answered, and the active permission mode.

Symptom	Likely cause
login failed: invalid username or password	Using an Ubiquiti SSO account instead of a local account, or the account has 2FA.
requires two-factor authentication (HTTP 499)	Create a local account without 2FA.
Could not reach the UniFi console	Wrong UNIFI_HOST, or the machine cannot reach the console. Try curl -k https://<host>/ first.
self-signed certificate errors	Leave UNIFI_VERIFY_TLS=false.
Protect tools say unreachable	Protect is not installed on this console, or the API key lacks Protect access. Set UNIFI_ENABLE_PROTECT=false to hide the tools.
A tool is missing from the list	It needs a higher permission tier, or the corresponding application is disabled.
only available through the internal UniFi Network API	That data is not in the Integration API — add UNIFI_USERNAME/UNIFI_PASSWORD.

---

Development

npm install
npm run build          # compile TypeScript to dist/
npm run typecheck      # types only
npm run inspect        # MCP Inspector against the local build
npm run bundle         # build unifi-mcp-<version>.mcpb

Adding a tool: define it with defineTool() in src/tools/, declare its tier and feature, and export it from src/tools/index.ts. scripts/sync-manifest-tools.mjs keeps manifest.json in step (it runs as part of npm run bundle).

Releasing

npm version minor          # bumps package.json and creates the v-tag
git push --follow-tags

The release workflow builds the bundle and attaches unifi-mcp-<version>.mcpb plus SHA256SUMS.txt to the GitHub release.

---

Compatibility

Developed against UniFi OS 4.x with UniFi Network 9.x and UniFi Protect 6.x on a UDR, with in-wall and standalone access points, an LTE camera and a doorbell. Other UniFi OS consoles use the same API surface. Endpoints that a given console or firmware does not implement return a clear error rather than failing silently.

License

MIT — see LICENSE.

Not affiliated with, endorsed by, or supported by Ubiquiti Inc. UniFi is a trademark of Ubiquiti Inc.