unifi-mcp MCP工具

UniFi account requirements

The MCP servers authenticate to the local UniFi controller APIs with a local admin/service account. Do not use a Ubiquiti SSO cloud account for MCP setup. For Network MCP today, accounts that require SSO MFA or local 2FA are not supported through configuration; use a dedicated local admin account without MFA for the service account, scoped to the permissions you are comfortable giving the MCP server.

Install with your agent

Paste the block below into your coding agent. It points the agent at the canonical, versioned setup guide and limits what it may change:

Install UniFi MCP for me using the official instructions at:
https://github.com/sirkirby/unifi-mcp/blob/main/docs/agent-install.md

Before changing anything, identify my agent client and operating system, ask
whether I need Network, Protect, Access, or more than one, and show me the exact
commands and configuration files you plan to change. Wait for my confirmation.
Do not ask me to paste a password or API key into chat. Prefer an indirect
credential provider or the client's secure secret prompt. Keep mutation
permissions in confirm mode and explicitly deny create, update, and delete
unless I opt in. After setup, reload the client, verify the MCP connection and
tool list, and run one harmless read-only check.

The guide covers native plugins, product-scoped npx skills add installs, OpenCode's built-in MCP support, and the current manual paths for Antigravity, Cursor, and Devin Desktop. A skills install adds agent guidance; it does not by itself register the MCP server.

See the changelog for what each plugin release changed, and the plugin upgrade guide before updating an existing install.

Multi-controller setups

Each server supports its own prefixed environment variables that take priority over the shared UNIFI_* variables. This lets you point the Network and Protect servers at different controllers (or different credentials) while keeping a single trusted env file explicitly loaded by the launcher:

Single controller? Just set the shared UNIFI_* variables -- all servers will use them. Server-specific variables are only needed when the servers talk to different controllers or use different credentials.

For the full configuration reference including permissions, transports, and advanced options, see the Network server docs, Protect server docs, or Access server docs.

Quick Start

Usage Examples

Once connected, just ask your AI agent in natural language:

Network > "Show me all clients on the Guest VLAN with their signal strength and data usage" > "Create a firewall rule that blocks IoT devices from reaching the internet between midnight and 6 AM" > "Audit my firewall policies — are there any redundant or conflicting rules?" > "Show me the top traffic flows from the last hour and group them by destination"

Protect > "List all cameras that detected motion in the last hour" > "Show me smart detection events from the front door camera today — people and vehicles only" > "Find driveway detections for white vans this week"

Access > "Who badged into the office today? Show me a timeline of all door access events" > "Create a visitor pass for John Smith with access to the main entrance tomorrow 9-5"

UniFi Intelligence (the unifi-intelligence plugin) > "Switch aa:bb:cc:00:10:02 dropped off at 8:45 this morning, New York time. What happened between 8:00 and 9:00?" — cites Network events and mapped Protect camera events with their coverage > "Show me everything that happened at the front entrance in the last hour" — needs the cloud worker and relay

All mutations use a preview-then-confirm flow — you see exactly what will change before anything is applied.

Configuration

Set these variables in the server's process environment (shell exports, the MCP client's env block, or Docker environment: / env_file:):

Startup configuration: The servers do not automatically load .env files or config/config.yaml from the working directory. MCP clients may launch servers inside untrusted projects, so project files must not control where credentials are sent or weaken permissions and redaction. If you previously relied on automatic loading, select a trusted env file in your launcher (for example, uv run --env-file /absolute/path/to/trusted.env --with unifi-network-mcp unifi-network-mcp) or set an absolute CONFIG_PATH for custom YAML. Docker Compose env_file: remains supported.

Per-user settings file: UNIFI_SETTINGS_FILE names a file the server reads at startup, before anything else reads configuration. The Codex plugin's setup writes ~/.config/unifi-mcp/<product>.env and points its bundled server at it. The file holds KEY=VALUE lines (# comments, optional matching quotes; no export, interpolation or multi-line values). Only UNIFI_* keys are accepted, and each behaves exactly as if exported, including _FILE / _COMMAND providers and policy gates. Variables already in the process environment win. A missing file is not an error. On POSIX the file must be owned by you and not group- or world-writable (keep it chmod 600); Windows has no mode check, so keep it in your user profile.

To keep the secret out of the MCP client's environment (and out of every process the client spawns), set UNIFI_PASSWORD_FILE to a path whose contents are the password, or UNIFI_PASSWORD_COMMAND to an absolute argv whose stdout is the password (contract). The same _FILE / _COMMAND suffixes work on UNIFI_API_KEY and on the per-server variables below. Details are in each server's docs/configuration.md.

REST + GraphQL API

unifi-api-server is an independent HTTP service for custom applications, automation, and adapters. It provides typed REST resources, read-only GraphQL queries, SSE streams, scoped API keys and administration, plus a REST action endpoint for supported controller operations. It shares unifi-core managers with the MCP servers but does not proxy or require them.

See apps/api/README.md for quick-start and deployment patterns.

Plugins

Install these from the Claude Code, Codex or OpenClaw marketplace; Quick Start shows how.

The Agent Skills table lists every skill each plugin ships.

Choose an integration

An MCP adapter can expose a small set of tools while using unifi-api-server as its backend. This keeps application-specific joins, branching, loops, and code isolation out of the general-purpose MCP servers.