UniFi Fabric MCP Server

Ask your AI assistant to check and manage your UniFi network.

📦 Installation · ▶️ Watch demo · ⚙️ How it works · 🛡️ Security · 📚 More info

UniFi Fabric MCP Server connects your AI assistant to your UniFi network. Find
offline devices, dig into Wi-Fi problems, review cameras, or change settings just
by asking.

It works through UniFi Fabrics, which put your sites and companies under one
organization in UniFi Site Manager. Join your consoles to
a fabric, create a fabric API key, and you're set. One key covers the whole
organization, and the server runs on your own computer or server. Everything goes
through Ubiquiti's cloud, so it never needs to reach a controller on your local
network.

What you can do

Ask your assistant to help with tasks such as:

“List my UniFi sites and the devices in each one.”
“Which devices are offline, and what should I investigate?”
“Show me the recent events from my Protect cameras.”
“Show me the floor plans in my InnerSpace project.”

You can also manage networks, Wi-Fi and firewall policies. See
tool usage and the tools reference for details.

Features

792 tools, loaded on demand. Discovery mode gives your assistant a small
search-and-call toolset instead of flooding its context with the whole catalog;
the full catalog is one setting away.
Deep Network and Protect coverage, plus InnerSpace. Networks, Wi-Fi, VPN,
firewall, clients, devices, cameras and floor plans; see
tool families for what is and is not covered.
Multi-site and multi-organization. One fabric key covers every site in the
organization, and you can configure several keys to manage many organizations
from one server. See the MSP guide.
Ready for shared deployments. Run it over HTTPS behind a gateway: request
headers can carry each caller's own API keys (the server stores none) and tighten
write policy or tool families per request, so one server can safely serve many
users. See header key mode.
Write controls. allow, dry-run or deny globally, with per-family and
per-tool exceptions.
Everything is a switch. Expose only the tool families you want, hide
individual tools, run discovery mode or advertise the full catalog, and opt into
redaction and audit logging; all of it is environment settings, no code changes.
See the configuration guide.
Secret redaction and audit logging. Mask credential fields in responses and
log every write attempt. See the configuration guide.
Any MCP client, any transport. stdio locally; HTTPS and SSE for servers,
with bearer-token or OAuth authentication and TLS served by the server itself
(bring your own certificate), up to mutual TLS. See
authentication and TLS.

Installation

1. Join your fabric and create an API key

Sign in to UniFi Site Manager. In the Sites sidebar under
Fabrics, create a fabric (Create New) if you don't have one, and make sure
the sites with your consoles are in it. New to fabrics? See Ubiquiti's
video and
announcement.
Select your fabric, then open API Keys
and select Create New API Key.
Enable at least Site Manager and Network scopes; add Protect for
cameras. Choose the sites the key can access.
Copy the key and store it securely. It is shown only once.

Treat the key like a password: each client stores it in plain text in its own
configuration file, so keep those files private.

2. Connect your assistant

[!NOTE]
The package commands below use the currently published 0.7.1 release. This README
describes 0.7.1 source. Upgrading from 0.7.0? See the migration guide
before changing settings.

The setups below run the server with uvx (from uv),
which fetches everything it needs — no Python setup required. Prefer pip? See the
client setup guide.

Claude Code

With Claude Code 2.1.275 or later, run:

/plugin marketplace add swkstudios/unifi-fabric-mcp-server
/plugin install unifi-fabric@unifi-fabric

Enter your API key when prompted. Or skip the plugin and add the server directly
from a terminal (the first line prompts for your key):

printf 'UniFi API key: '; read -rs UNIFI_API_KEY; echo; export UNIFI_API_KEY
claude mcp add unifi-fabric -e UNIFI_API_KEY="$UNIFI_API_KEY" -- uvx --from unifi-fabric-mcp-server==0.7.1 unifi-fabric-mcp

Claude Desktop

Open Settings > Developer > Edit Config and merge the following into the
configuration:

{
  "mcpServers": {
    "unifi-fabric": {
      "command": "/absolute/path/to/uvx",
      "args": ["--from", "unifi-fabric-mcp-server==0.7.1", "unifi-fabric-mcp"],
      "env": { "UNIFI_API_KEY": "your-api-key-here" }
    }
  }
}

Replace the command path with the output of which uvx on macOS or where uvx
on Windows, and replace the key placeholder. Quit Claude Desktop completely and
reopen it.

Alternatively, download the Claude Desktop extension (.mcpb)
and open it; Claude Desktop prompts for your API key during installation.

Codex

From a terminal (the first line prompts for your key):

printf 'UniFi API key: '; read -rs UNIFI_API_KEY; echo
codex mcp add unifi-fabric --env UNIFI_API_KEY="$UNIFI_API_KEY" -- uvx --from unifi-fabric-mcp-server==0.7.1 unifi-fabric-mcp

This stores the key in ~/.codex/config.toml. Run codex mcp list to check the
registration.

Google Antigravity

Export the key before starting agy — that keeps it out of config files
(Antigravity does not expand ${VAR} in env values):

printf 'UniFi API key: '; read -rs UNIFI_API_KEY; echo; export UNIFI_API_KEY
agy mcp add unifi-fabric -- uvx --from unifi-fabric-mcp-server==0.7.1 unifi-fabric-mcp
agy

When Antigravity is started from the Dock (Antigravity 2.0 and the IDE), it cannot
see exported variables; store the key in the config instead:

agy mcp add --env UNIFI_API_KEY="$UNIFI_API_KEY" unifi-fabric -- uvx --from unifi-fabric-mcp-server==0.7.1 unifi-fabric-mcp

Gemini CLI

Install this repository as a Gemini CLI extension; it prompts for your API key
(stored in the system keychain) and your write-policy choice:

gemini extensions install https://github.com/swkstudios/unifi-fabric-mcp-server

VS Code

Use the install button above, or add this to .vscode/mcp.json in your workspace
(VS Code prompts for the key on first start):

{
  "inputs": [
    { "id": "unifi_api_key", "type": "promptString", "description": "UniFi Fabric API key", "password": true }
  ],
  "servers": {
    "unifi-fabric": {
      "command": "uvx",
      "args": ["--from", "unifi-fabric-mcp-server==0.7.1", "unifi-fabric-mcp"],
      "env": { "UNIFI_API_KEY": "${input:unifi_api_key}" }
    }
  }
}

Cursor

Use the install button above, or merge this into ~/.cursor/mcp.json and replace
the key placeholder:

{
  "mcpServers": {
    "unifi-fabric": {
      "command": "uvx",
      "args": ["--from", "unifi-fabric-mcp-server==0.7.1", "unifi-fabric-mcp"],
      "env": { "UNIFI_API_KEY": "your-api-key-here" }
    }
  }
}

ChatGPT

ChatGPT cannot launch a local MCP server. It connects over the network, signed in
through OAuth — so using it means self-hosting:

Run this server in OAuth mode (MCP_AUTH_MODE=oauth) behind an identity
provider you operate.
Make it reachable from ChatGPT: a public HTTPS URL behind a TLS proxy, or a
private connection through
OpenAI's Secure MCP Tunnel
(no public exposure needed).
In ChatGPT, open Plugins, select +, then Add custom MCP server, and
choose OAuth.

The ChatGPT guide walks through each step and has a security
checklist. Never expose the server without authentication: it can reconfigure
your network.

Any other MCP client

Run the server locally over stdio (Python 3.12+, or let uv fetch one):

export UNIFI_API_KEY="your-api-key-here"
uvx --from unifi-fabric-mcp-server==0.7.1 unifi-fabric-mcp

Or register it with the standard MCP configuration your client reads:

{
  "mcpServers": {
    "unifi-fabric": {
      "command": "uvx",
      "args": ["--from", "unifi-fabric-mcp-server==0.7.1", "unifi-fabric-mcp"],
      "env": { "UNIFI_API_KEY": "your-api-key-here" }
    }
  }
}

Prefer a one-time install with pipx install unifi-fabric-mcp-server==0.7.1 or
uv tool install unifi-fabric-mcp-server==0.7.1, then use
"command": "unifi-fabric-mcp" with no args.

Docker (self-hosted HTTP server)

Run the server as a container that your MCP clients reach over HTTP with a bearer
token, so only clients holding the token can use your UniFi key:

# Generate a random token once and keep it: the server checks it and your MCP client sends it.
export MCP_BEARER_TOKEN="$(openssl rand -hex 32)"
docker run -e UNIFI_API_KEY="your-api-key-here" -e MCP_AUTH_MODE=bearer -e MCP_BEARER_TOKEN \
  -p 127.0.0.1:3000:3000 ghcr.io/swkstudios/unifi-fabric-mcp-server:0.7.1

Point your client at it with an HTTP entry (the token stays in your environment):

{
  "mcpServers": {
    "unifi-fabric": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": { "Authorization": "Bearer ${MCP_BEARER_TOKEN}" }
    }
  }
}

-p 127.0.0.1:3000:3000 serves this machine only; to serve other machines, publish
the port and add TLS. The Docker guide has the smoke test, digest
pinning and TLS options.

Full walkthroughs for every client are in the client setup guide.

3. Ask your first question

Ask your assistant: “List my UniFi sites and the devices in each one.”
If it answers with your sites, you are connected — everything in
What you can do works from here.

How it works

By default, the server exposes a small set of discovery tools to your assistant rather
than loading the entire 792-tool catalog into context at once. When you ask a question
or request a change, the assistant searches the catalog, inspects the matching tool, and
calls it through the server.

The server sends the request over HTTPS with your UniFi Fabric API key to the UniFi
Fabric API (api.ui.com). Ubiquiti's cloud relays the request to the consoles joined
to your fabric,
which reach your network devices and Protect deployment, and returns the response along
the same path. You do not need to open inbound ports, log in directly to a controller,
or install software on your consoles.

Tool families

Catalog: 792 registered tools; 773 are in the product
families listed below. The remaining 19 cover Ubiquiti's ISP and
mobile-routing products (Carrier Fabric and Mobility), which this overview
leaves out. Availability depends on your hardware, permissions and API routes;
see coverage and limitations.

Family	Tools	Family	Tools
Network	343	Protect	227
VPN	42	Devices	37
Firewall	33	InnerSpace	32
Site Manager	19	Statistics	16
Clients	15	Connector relay	5
Hotspot	4

Verification status

Evidence	Result
Every tool runs in CI against a simulated upstream	792 tools
Live-tested on a real console	380 of 786 passed on build `cde04b5c1520`, 2026-10-28
Live write tools passed	114 on that build and date

Full results, failures and untested tools are in
coverage and limitations.

Security

[!IMPORTANT]
Writes are allowed by default — the server can change your network. One setting
controls that:

Setting	Effect
`UNIFI_WRITE_POLICY=allow`	Default: read and write tools are available.
`UNIFI_WRITE_POLICY=dry-run`	Writes return a preview of what would be sent; nothing changes.
`UNIFI_WRITE_POLICY=deny`	Read-only: write tools are hidden and refused.

# example: run read-only
export UNIFI_WRITE_POLICY=deny

Per-family and per-tool exceptions are available through UNIFI_WRITE_EXCEPTIONS;
see the configuration guide.
Upgrading from an older release? The variable names changed; see the migration guide.

Review requests before they run — use your MCP client's permission prompts.
Responses can contain sensitive data — the server masks its own configured
secrets; set UNIFI_REDACT_SECRETS=1 to also mask documented credential fields
(Wi-Fi PSKs, RADIUS secrets, tokens).
Protect your files — client config files and logs hold your API key; keep
them private.
Remote deployments need authentication and TLS — see
authentication and TLS.

Verify the image

Release images are signed with Cosign and carry an SBOM and provenance attestation; see Verify the image.

More info

Guide	What it covers
Configuration	Every setting: discovery, write controls, audit logging
Client setup	Full walkthroughs for every supported MCP client
Troubleshooting	Fixes for common setup, connection and key errors
Docker deployment	Running as a shared HTTP service with auth and TLS
Migration guide	Upgrading from an older release
Tool usage	Workflows and examples for using the tools
Tool reference	Every tool, listed by family
Coverage	Live-verification results, compatibility and limits
Agent skills	Ready-made skills for AI assistants
MSP setup	Managed-service and multi-organization use
Introducing UniFi Fabrics	Ubiquiti's announcement of fabrics, with a video overview

Project: Privacy · Security policy · Contributing · License

This project is not affiliated with or endorsed by Ubiquiti. UniFi is a trademark of
Ubiquiti Inc. Licensed under the MIT License.