Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@UniFi MCP Which devices are on my WiFi right now, and which access point are they on?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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)
Related MCP server: UniFi MCP Server
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.
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.
.mcpb)Download unifi-mcp-<version>.mcpb from the latest release.
Open Claude Desktop → Settings → Extensions and drag the file in (or double-click it).
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
npxexamples 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.
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-mcpAdd 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"
}
}
}
}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 stdioUniFi 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 |
|
|
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.)
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 |
| Plugin toggles | What it adds |
Read-only (default) |
| both off | Reading only. Nothing on your network can change. |
Actions |
| 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 |
| Allow configuration changes | Firewall rules, port forwards, WiFi and network settings, firmware upgrades, Protect recording modes, and write access through |
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.
Tool | What it does |
Console | |
| 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. |
| 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 | |
| List the UniFi Network sites on this console, with the site name to pass to other tools. |
| List adopted UniFi devices (gateway/router, access points, switches) with model, state, firmware, uptime, client count and load. |
| Full details for one UniFi device by MAC address, including radios, ports, temperatures and uplink. |
| List clients on the network with IP, signal, throughput and which access point or switch port they use. |
| List all clients the controller has ever seen, including offline ones, their fixed IPs, notes and blocked state. |
| List the configured SSIDs with security settings, band and enabled state. |
| List LANs, VLANs and WAN configuration including subnets and DHCP ranges. |
| List port forwarding rules on the gateway. |
| List firewall rules (and optionally firewall groups) configured on the gateway. |
| Overall health per subsystem (WAN, LAN, WLAN, VPN): status, uptime, latency, throughput and last speedtest result. |
| Recent Network events: client connect/disconnect, roaming, device restarts, configuration changes. |
| Open (or archived) alarms raised by the Network application. |
| Time series statistics for the site, an access point, the gateway or a single client (throughput, clients, latency). |
| List guest hotspot vouchers with their duration, quota and usage. |
UniFi Protect | |
| Version, storage and recording status of the UniFi Protect NVR running on this console. |
| List cameras and doorbells with connection state, recording mode, battery level and last motion/ring. |
| Full details of one camera or doorbell, including its feature flags and settings. |
| Fetch a current still image from a camera or doorbell and return it as an image so it can be looked at directly. |
| Recent Protect events: motion, smart detections (person, vehicle, package), doorbell rings and device connect/disconnect. |
| List Protect sensors, lights, chimes, viewers and doorlocks. |
| Return the RTSPS URL for a camera so it can be opened in VLC, ffmpeg or a media player. |
Tool | What it does |
UniFi Network | |
| Block a device from the network, or lift an existing block. Fully reversible with the same tool. |
| Force a wireless client to reconnect (kick). Useful to push a device to another band or access point. |
| Authorize a client on the guest portal for a period of time, or revoke that access. |
| Give a client a friendly name and/or a note in the controller. |
| Restart an access point, switch or the gateway itself. A soft restart reboots the software; hard power-cycles. |
| Make a UniFi device flash its LED so you can find it physically, or stop flashing. |
| Power-cycle a PoE switch port, restarting whatever is plugged into it. |
| Turn an SSID on or off, for example a guest or IoT network. |
| Start a speed test on the gateway, or read the status of the running test. |
| Create one or more guest hotspot vouchers. |
| Delete a guest voucher so it can no longer be used. |
UniFi Protect | |
| Show a custom message on a UniFi doorbell's screen, or reset it to the default. Reversible. |
| Force a UniFi Protect floodlight on or off, or hand control back to motion detection. |
Tool | What it does |
UniFi Network | |
| Turn an existing port forwarding rule on or off. |
| Turn an existing firewall rule on or off. |
| Patch settings on an SSID (name, password, band, guest policy, ...). Only the supplied keys change. |
| Patch settings on a LAN/VLAN/WAN definition. Only the supplied keys change. |
| Start a firmware upgrade on a UniFi device. The device reboots when it finishes. |
UniFi Protect | |
| Set when a camera records: always, only on detections, or never. This affects your security footage. |
| 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.
Variable | Default | Description |
| (required) | Hostname or IP of the console. |
| — | API key for the official Integration API. |
| — | Local UniFi OS account for the internal API. |
| — | One-time 2FA code, if you really must use an account that has it. |
|
| Network site name. |
|
|
|
|
| Boolean alternative that maps to |
|
| Boolean alternative that maps to |
|
| Expose the Network tools. |
|
| Expose the Protect tools. |
|
| Verify the console's certificate. Consoles use a self-signed certificate on their local address. |
|
| Per-request timeout. |
At least one credential set is required; the server exits with an explanation if none is configured.
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.
Run unifi_status first — it reports which credentials authenticated, which applications answered, and the active permission mode.
Symptom | Likely cause |
| Using an Ubiquiti SSO account instead of a local account, or the account has 2FA. |
| Create a local account without 2FA. |
| Wrong |
| Leave |
Protect tools say | Protect is not installed on this console, or the API key lacks Protect access. Set |
A tool is missing from the list | It needs a higher permission tier, or the corresponding application is disabled. |
| That data is not in the Integration API — add |
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>.mcpbAdding 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).
npm version minor # bumps package.json and creates the v-tag
git push --follow-tagsThe release workflow builds the bundle and attaches unifi-mcp-<version>.mcpb plus SHA256SUMS.txt to the GitHub release.
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.
MIT — see LICENSE.
Not affiliated with, endorsed by, or supported by Ubiquiti Inc. UniFi is a trademark of Ubiquiti Inc.
This server cannot be installed
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/mbgroen/unifi-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server