UniFi MCP

Leverage agents and agentic AI workflows to manage your UniFi deployment.

Servers

Cloud Relay

Cloud Relay pairs the Cloudflare-hosted Worker gateway with the Relay sidecar on your LAN. The Worker provides the authenticated edge MCP endpoint, Durable Object broker, multi-location routing, token boundary, and deployment/management CLI. The Relay sidecar is a local MCP HTTP client and forwarder: it discovers configured local MCP servers over HTTP and maintains an outbound WebSocket to the Worker. Remote requests follow MCP client → Worker gateway → outbound WebSocket → Relay sidecar → local MCP servers over HTTP; the API server is not in this path. Read-only tools support annotation-based multi-location fan-out, while writes require explicit location targeting. Deploy the Worker with npm install -g unifi-mcp-worker && unifi-mcp-worker install, then see the Relay sidecar README to connect local servers.

REST + GraphQL API (non-MCP)

unifi-api-server is an independent HTTP service for consumers that do not speak MCP. 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.

What is this?

UniFi MCP is a collection of Model Context Protocol servers that let AI assistants and automation tools interact with Ubiquiti UniFi controllers. Each server targets a specific UniFi application (Network, Protect, Access) and exposes its functionality as MCP tools — queryable, composable, and safe by default.

MCP HTTP Access

MCP HTTP is unauthenticated and intended for trusted local clients. HTTP is disabled by default; when enabled, packages bind to loopback. Docker Compose enables it on the container network and publishes ports 3000–3002 on host 127.0.0.1. Use an authenticated TLS proxy or Cloud Relay for remote access, and prevent direct access to the backend. See the transport security model and HTTP setup and migration.

MCP Discovery

UniFi MCP keeps the standard MCP path primary: capable clients discover currently registered tools with tools/list and invoke them with tools/call. The default lazy mode keeps initial context small by exposing meta-tools first, while eager mode registers all selected domain tools directly for clients that prefer a full standard tool list.

The lazy-loading meta-tools — *_tool_index, *_execute, *_batch, *_batch_status, and lazy-only *_load_tools — support filtered discovery, indirect execution, batch orchestration, and optional direct registration. They are independent of the protocol-version response compatibility policy below. See MCP Discovery and Lazy-Loading Meta-Tools for mode-by-mode behavior.

MCP response size

For tool results that already provide structured output, adaptive response mode is the default. It classifies each request by the canonical date-based protocolVersion advertised during MCP initialization, not by the client's product name or application version. Requests advertising MCP 2025-06-18 or later receive concise text in content and the full result once in structuredContent; requests advertising an earlier revision (such as 2024-11-05 or 2025-03-26), or whose revision metadata is missing or malformed, retain the full compatibility JSON in content. Set UNIFI_MCP_CONTENT_MODE=compat to force that duplicated compatibility form, or UNIFI_MCP_CONTENT_MODE=compact to force concise text plus the full structured result even outside a negotiated request. Use compat for any client that consumes the full result only from content, regardless of its advertised revision.

The lazy-loading meta-tools remain content-only; they are not the pre-2025-06-18 protocol category described above. For structured inner results, *_execute and *_batch_status expose one normalized JSON payload in content rather than a nested transport pair; content-only execute results remain unchanged. Response modes do not convert these meta-tools to structuredContent.

UNIFI_NETWORK_MCP_CONTENT_MODE, UNIFI_PROTECT_MCP_CONTENT_MODE, and UNIFI_ACCESS_MCP_CONTENT_MODE override the global setting for their respective servers. Independently of transport compaction, Network's unifi_get_dashboard defaults to summary=true, while unifi_list_rogue_aps defaults to a summarized page of at most 100 records; pass summary=false when the full selected data is required.

Quick Start

Claude Code (recommended)

Install via the plugin marketplace — includes the MCP server, an agent skill, and guided setup:

/plugin marketplace add sirkirby/unifi-mcp
/plugin install unifi-network@unifi-plugins
/unifi-network:unifi-network-setup

Repeat for Protect or Access if needed:

/plugin install unifi-protect@unifi-plugins
/plugin install unifi-access@unifi-plugins

Each plugin's setup command walks you through connecting to your controller and configuring permissions.

Codex

Register the UniFi MCP marketplace, then install the plugins from Codex's /plugins UI:

codex plugin marketplace add sirkirby/unifi-mcp

Launch codex, run /plugins, open the UniFi MCP marketplace, and install unifi-network, unifi-protect, or unifi-access. After installing, ask Codex to run the plugin's setup skill, for example:

Use the unifi-network-setup skill to configure this for Codex.

The setup skill registers the MCP server with codex mcp add, stores the selected environment values in Codex's MCP configuration, and keeps the same preview-before-confirm safety model as Claude Code.

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.

OpenClaw

OpenClaw can install the same UniFi plugin bundles from the marketplace and map their skills plus MCP server definitions into embedded Pi sessions:

openclaw plugins install unifi-network --marketplace https://github.com/sirkirby/unifi-mcp
openclaw gateway restart

Then run the matching setup skill from OpenClaw (unifi-network-setup, unifi-protect-setup, or unifi-access-setup), or configure the server directly:

openclaw mcp set unifi-network '{
  "command": "uvx",
  "args": ["--python-preference", "system", "unifi-network-mcp@latest"],
  "env": {
    "UNIFI_NETWORK_HOST": "192.168.1.1",
    "UNIFI_NETWORK_USERNAME": "admin",
    "UNIFI_NETWORK_PASSWORD": "your-password"
  }
}'

Repeat with unifi-protect or unifi-access as needed. Restart the OpenClaw Gateway after changing MCP server configuration.

Other MCP clients

Run the servers directly:

uvx unifi-network-mcp@latest
uvx unifi-protect-mcp@latest
uvx unifi-access-mcp@latest

For Claude Desktop, add to your claude_desktop_config.json: