UniFi MCP

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.

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.

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

Actions (safe)

Configuration (full)

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

Configuration reference

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.

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.