unifi-mcp
Provides tools for interacting with a UniFi gateway's local Network and Protect APIs, including retrieving gateway/site information, health, devices, clients, and port-forward rules, searching and describing API operations, running read operations, and performing guarded create, update, delete, and port-forward changes with dry-run and confirmation safeguards.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
unifi-mcp
Unofficial. Not affiliated with or endorsed by Ubiquiti Inc. UniFi and UniFi Protect are trademarks of Ubiquiti Inc. This server can change your network: changes are a dry run unless you confirm them, many write operations have not been tried on real gateways, and you use it at your own risk (MIT licence, no warranty). Report security problems as described in
SECURITY.md.
A small MCP server for a UniFi gateway's local API (a UDM, UDM Pro, UCG and so on, Network 9+), written so that one person can read all of it. Nothing leaves your network.
Install and sign in
Needs Node 24 or newer. First sign in once, in a terminal:
npx -y @mmoonport-labs/unifi-mcp setupIt asks for the gateway address (an IP or URL) and an API key (create one in UniFi: Settings > Control Plane > Integrations; typing is hidden). It then shows the gateway's certificate fingerprint, and you approve it once: the key is only ever sent to a gateway presenting that certificate. It checks that the key works before saving anything. The address and fingerprint go to ~/.config/unifi-mcp/config.json; the key goes to the macOS Keychain or the Linux keyring (libsecret's secret-tool), or, where neither exists, to a file only you can read (~/.config/unifi-mcp/key, mode 600). npx -y @mmoonport-labs/unifi-mcp logout forgets all of it.
Then add it to your client, with no environment variables.
Claude Code, with the skill (recommended):
/plugin marketplace add mmoonport-labs/unifi-mcp
/plugin install unifi@unifi-mcpThis installs the server and the unifi skill together. See Permissions below for asking before changes: a plugin cannot set permission rules for you.
Claude Code, server only: claude mcp add unifi -- npx -y @mmoonport-labs/unifi-mcp
Other clients: see "Use with other MCP clients".
Environment variables (below) still work and win over what setup saved, which suits CI and containers. A saved key and fingerprint are only used for the saved address.
Related MCP server: unifi-mcp
Tools
Tool | What it does |
| Network and Protect versions, sites, the loaded spec versions, and |
| every port-forward rule (id, name, enabled, WAN address and port, LAN target, protocol) |
| site health by subsystem |
| adopted devices (name, model, firmware, state) |
| connected clients |
| changes the router: enable or disable a rule, or change its LAN target ( |
Three more tools cover the rest of the gateway API without a tool per endpoint:
Tool | What it does |
| find operations by words, tag, risk or api |
| parameters and full request-body schema of one operation |
| run a read operation |
| changes the router: run a create or update operation; dry run by default |
| deletes: run a delete operation; dry run by default |
The catalog is every operation of Ubiquiti's official Network and Protect integration APIs (about 70 each), plus a table of the legacy Network endpoints the official API does not cover (read and write for firewall, networks, Wi-Fi, port forwards and clients; read only for rogue APs, DPI, hotspot, RADIUS, scheduled tasks and the newer v2 API's traffic rules, static DNS, NAT, ACL and QoS rules). See "API specs" below for where the OpenAPI documents come from.
How the write tool is guarded
Gated by your permissions. The write tools are always there; Claude Code asks you before each call (see "Permissions").
UNIFI_READ_ONLY=1refuses every change regardless.Dry run by default. It reads the rule and returns before and after; nothing is sent.
To apply, the call needs
dry_run=falseandconfirm=true. (The tool description tells the model to do this only after the owner says to.)fwdmust be a private LAN address; ports are checked; the rule id must exist.The reply carries the previous values and a ready
revertcall. Every applied change is logged to stderr (never the key).It sends the whole rule back with only your fields changed, using the gateway's older ("legacy")
rest/portforwardendpoint, because the official integration API has no port-forward endpoints we could find. The first real write has not been tried (see "Status").
Configuration (environment)
Variable | |
| required unless |
| required unless |
| recommended: pin the gateway's own certificate (its SHA-256 fingerprint). The key is not sent to any other certificate |
|
|
| site name, default |
| path to another copy of the Network or Protect OpenAPI spec (a newer download or one corrected by hand), used instead of the fetched one |
| where fetched specs are cached; default |
|
|
| a file to append every applied change to, one JSON object per line ( |
|
|
Get the fingerprint: openssl s_client -connect 192.168.1.1:443 </dev/null 2>/dev/null | openssl x509 -noout -fingerprint -sha256
Run from a source checkout (development)
npm ci && npm run build
claude mcp add unifi --scope user \
-e UNIFI_URL=https://192.168.1.1 -e UNIFI_CERT_SHA256=<fingerprint> \
-- ./scripts/run.shscripts/run.sh (macOS only; on other systems set UNIFI_API_KEY in the environment) reads the key from the macOS Keychain, so it is in neither the repo nor Claude's config:
security add-generic-password -a "$USER" -s unifi-mcp -w # asks for the keyUse with other MCP clients
The server speaks standard MCP over stdio, so any client that can start a local server works. Run setup once (see Install), or give it UNIFI_URL, UNIFI_API_KEY and UNIFI_CERT_SHA256 (see Configuration). The generic entry (with the environment shown, which you can leave out after setup), which most clients' JSON config takes under mcpServers (Claude Desktop, Cursor, Windsurf, Gemini CLI):
{
"mcpServers": {
"unifi": {
"command": "node",
"args": ["/absolute/path/to/unifi-mcp/dist/index.js"],
"env": { "UNIFI_URL": "https://192.168.1.1", "UNIFI_API_KEY": "...", "UNIFI_CERT_SHA256": "..." }
}
}
}VS Code (Copilot) uses a servers key in .vscode/mcp.json; Codex CLI uses [mcp_servers.unifi] in ~/.codex/config.toml with the same command, args and env. Check your client's documentation for the exact file.
The guidance travels with the server. It sends instructions when a client connects, serves the longer guide (workflow, gotchas, recipes) as the resource unifi://guide and as the prompt unifi_guide, and describes every tool. It also offers four one-click read-only prompts (network_health_check, who_is_on_the_network, troubleshoot_client, security_review), which clients show as slash commands or in a prompt menu. A client that ignores instructions can still be told to read the guide. The Claude Code skill in skills/unifi is only a thin layer on top (spec upkeep, permissions).
Safety does not depend on the client. Allow/ask/deny rules by tool name are a Claude Code feature; other clients approve tools in their own way, and some approve everything. What always applies is the server's guard: every change is a dry run unless dry_run=false and confirm=true. For a client you do not trust to ask first, start the server with UNIFI_READ_ONLY=1.
API specs
Ubiquiti's OpenAPI documents are not part of this repository or package. At start-up the server asks the gateway for its Network and Protect versions and, if the cache has no spec for that version, downloads one: first from Ubiquiti's documentation CDN (apidoc-cdn.ui.com), then from the community repository beezly/unifi-apis, which extracts a spec from each release. If the gateway is newer than anything published, the nearest older release is used (unknown fields in a request then only warn). These downloads send nothing but the version number in the URL, and the files are only data, but they reach the model through the search and describe tools. With no spec at all the legacy operations still work and the official ones are missing; unifi_info says which spec is loaded. Set UNIFI_SPEC_AUTO_UPDATE=0 to stop the downloads.
npm test needs real specs too, so a pretest step downloads pinned copies into test/.specs (not committed).
Permissions
Claude Code decides, per tool, whether a call runs, asks you, or is refused. .claude/settings.json in this repo (for a checkout) allows the read tools and asks before unifi_write, unifi_set_port_forward and unifi_delete. To change that, edit the rules (or put them in ~/.claude/settings.json to apply everywhere):
{ "permissions": { "allow": ["mcp__unifi__unifi_write"], "deny": ["mcp__unifi__unifi_delete"] } }Installed as the plugin, the tool names carry the plugin's name (mcp__plugin_unifi_unifi__unifi_write), and your settings are yours to write. To ask before every change, put this in ~/.claude/settings.json (or a project's .claude/settings.json):
{
"permissions": {
"ask": [
"mcp__plugin_unifi_unifi__unifi_write",
"mcp__plugin_unifi_unifi__unifi_delete",
"mcp__plugin_unifi_unifi__unifi_set_port_forward"
]
}
}Allowing unifi_write without asking leaves only the dry-run and confirm=true guard, which the model fills in itself, so keep it on ask unless you trust the session. For a server that can never change anything, start it with -e UNIFI_READ_ONLY=1.
Development
nvm use && npm ci && npm test (100% coverage enforced; a fake gateway and a throwaway self-signed certificate, no real router). One ticket, one branch, one PR; Conventional Commits. CI runs the same checks on every pull request. How a release is made: RELEASING.md.
Status
Early (0.2). Tested in simulation (a fake gateway and local TLS) and against one real UDM Pro (Network 11.0.99, Protect 7.3.74). All the reads were run for real. Writes run for real so far are listed in guide/guide.md (under "When something fails"): legacy port forwards, a client rename, Wi-Fi settings and deletes, a network delete, and several official firewall policy and traffic list changes, plus a PoE power cycle. Every other write is untested: dry-run it first and read the record back afterwards. The gateway itself serves no API spec; the server fetches the one for its version (see "API specs"). UniFi Access is not covered.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Supervised API-write gateway for AI agents with policy, human approval and execution receipts.
Open-source MCP gateway with per-agent tool permissions, call approvals and tool-change review.
Security gateway for AI agents: policy, approval, and audited execution, no secrets shared.
Related MCP Servers
- AlicenseDqualityNot gradedmaintenanceEnables comprehensive management of UniFi network infrastructure through the UniFi Cloud API, including device control, client management, camera settings, and access door control through natural language.39MIT
- AlicenseNot gradedqualityCmaintenanceA safety-first MCP server for managing UniFi networks, exposing 17 tools for telemetry, diagnostics, and guarded mutations with dry-run previews and confirm requirements.16MIT
- AlicenseAqualityBmaintenanceProvides read-only access to UniFi Network consoles for sites, devices, clients, vouchers, networks, Wi-Fi, and firewall configuration, with optional opt-in tools for controlled write operations and legacy controller support.14256 npmMIT
- AlicenseAqualityCmaintenanceEnables local UniFi Network inspection and management through MCP, providing typed read-only inventory of sites, devices, clients, and networks, with preview-first, explicitly confirmed device rename and LED locate operations.8MIT