How to Enable UniFi MCP Locally to View and Manage Network Components and Devices

Outcome

Enable UniFi MCP in local gateway mode so AI agents can view and manage network components and devices through the local controller, starting with safe read validation and dry-run write checks before live changes.

Audience and Scope

Audience	New users who want to give AI agents controlled access to UniFi Network
Difficulty	Beginner
Estimated Time	20 to 30 minutes
Assumptions	You have a UniFi gateway or controller on your LAN, an owner or super admin account, and a secure way to store the API key

Before You Start

Confirm you can reach your local controller in a browser
Use an owner or super admin account that can open the Network app and the Integrations page
Choose a secure secret-loading pattern such as 1Password CLI or another secret manager
Know which site you want agents to manage

Hardware and Software

Hardware

A UniFi gateway, controller, or Cloud Gateway on your local network
A workstation or server that launches your MCP clients

Software

UniFi Network
A secret-loading tool such as 1Password CLI
The unifi-mcp-server package launched by a local wrapper script
At least one MCP client configuration file

Step-by-Step

Step 1: Confirm local controller access

Objective: Make sure you can reach the local controller and identify the site you want to manage.

Actions:

Open the local controller in a browser and sign in
Open the UniFi Network application for the site you want to manage
Record the controller address and the site name

Copy targets:

https://<your-controller-host-or-ip>
<your-site-name>

Verification:

The local Network app opens successfully
You can identify the site you want to manage

Common failure and fix: If you land on Site Manager first, continue into the local Network app for the target site.

Step 2: Create a local API key

Objective: Generate the API key that the UniFi MCP wrapper will use.

Actions:

Open the Integrations page in UniFi Network
Create a new key
Copy the full key value immediately

Copy targets:

Settings > Control Plane > Integrations
unifi-mcp-local

Verification:

You have the full key value once
The key is saved before you leave the page

Common failure and fix: If Integrations is missing, switch to the owner account.

Step 3: Store the key securely

Objective: Save the key in a secret store instead of placing it directly in the client config.

Actions:

Create or update the vault item that will hold the UniFi API key
Paste the key into the correct secret field
Reference that field from the env file or wrapper

Copy targets:

<your-vault-name>
<your-item-name>
op://<vault>/<item>/password

Verification:

The secret reference resolves to the current API key
The raw key is not stored in the MCP client config

Common failure and fix: If authentication later returns 401 Unauthorized, confirm the full key was stored without extra spaces and that your secret-loading tool is resolving the right field.

Step 4: Switch UniFi MCP to local mode

Objective: Configure the UniFi MCP wrapper for direct local gateway access.

Actions:

Edit the env file used by your UniFi MCP wrapper
Set the API mode to local
Point the host, port, SSL behavior, and site name at the correct local controller

Copy targets:

/path/to/unifi-mcp.env

UNIFI_API_KEY=<your-secret-reference-or-api-key>
UNIFI_API_TYPE=local
UNIFI_LOCAL_HOST=<your-controller-host-or-ip>
UNIFI_LOCAL_PORT=443
UNIFI_LOCAL_VERIFY_SSL=false
UNIFI_DEFAULT_SITE=<your-site-name>

Verification:

The env file is set to local mode
The host and site name match the local controller you want to manage

Common failure and fix: If your controller uses a trusted certificate, change the SSL verification line in the env block to true. If you use the default local certificate, keep that line set to false.

Step 5: Wire the wrapper into your MCP clients

Objective: Make sure every MCP client launches the same secret-backed UniFi wrapper.

Actions:

Confirm the wrapper script path
Confirm your client config points to that wrapper
Apply the same server entry anywhere you share MCP configuration across tools

Copy targets:

/path/to/unifi-mcp-op.sh
/path/to/config.toml
/path/to/.mcp.json

[mcp_servers.unifi-mcp]
command = "/path/to/unifi-mcp-op.sh"
args = []

Verification:

Each MCP client points to the same wrapper
No raw UniFi secrets appear in the client config files

Common failure and fix: If one client works and another does not, compare the wrapper path and command entry in each config file.

Step 6: Restart your agent clients

Objective: Reload the UniFi MCP process with the updated env file and wrapper configuration.

Actions:

Restart your MCP clients
Start a fresh session after the restart

Verification:

New sessions pick up the local-mode env
Stale sessions no longer report cloud-only behavior

Common failure and fix: The most common issue is testing from an already-open session that still has the old UniFi MCP process attached.

Step 7: Validate read access

Objective: Confirm the local controller returns real data before you allow live changes.

Actions:

Run a direct probe against the local controller
Run a basic set of read-only MCP checks
Run at least one dry-run write-class check before any live change

Copy targets:

curl -sk -H "X-API-KEY: $UNIFI_API_KEY" 
  https://<your-controller-host-or-ip>/proxy/network/integration/v1/sites

health_check
list_all_sites
search_devices
list_active_clients
list_vlans
list_wlans
get_network_topology

create_wlan(..., dry_run=true)
create_firewall_rule(..., dry_run=true)
restart_device(..., dry_run=true)

Verification:

The direct site probe returns 200
The read checks return real site, device, client, network, WLAN, and topology data
The dry-run checks succeed without creating a live change

Common failure and fix: If your session still reports cloud mode, restart the client and test again from a fresh session.

Step 8: Make one controlled live change

Objective: Prove real write authority with minimal risk.

Actions:

Create and delete a temporary test WLAN, or
Toggle locate mode on a single access point, or
Create and remove a harmless disabled firewall rule

Verification:

The change appears in UniFi
You can reverse it cleanly

Common failure and fix: If live changes fail but dry-run works, verify that the API key still has the required controller access.

Validation Checklist

The UniFi API key is stored in a secret store instead of hardcoded in a client config
The UniFi MCP env file uses local mode
Your MCP clients point to the same wrapper
Fresh local-mode reads return real controller data
At least one dry-run write path succeeds before any live change

Operations and Maintenance

Rotate the UniFi API key when the owner account or permissions change
Keep the service-account token or secret-loading runtime file restricted to the local admin account
Restart MCP clients after changing wrapper env files
Use dry-run first for firewall, VLAN, WLAN, and client-control operations

Troubleshooting and Rollback

401 Unauthorized: Recheck the stored API key and the secret reference that resolves it
Still in cloud mode: Restart the client session and open a fresh session
Missing local reads: Confirm the env file still points to the local controller and correct site name
Rollback: Temporarily switch the env file back to cloud mode, restart the client, and restore local mode only after the key problem is fixed

How to Enable UniFi MCP Locally to View and Manage Network Components and Devices

Outcome

Audience and Scope

Before You Start

Hardware and Software

Hardware

Software

Step-by-Step

Step 1: Confirm local controller access

Step 2: Create a local API key

Step 3: Store the key securely

Step 4: Switch UniFi MCP to local mode

Step 5: Wire the wrapper into your MCP clients

Step 6: Restart your agent clients

Step 7: Validate read access

Step 8: Make one controlled live change

Validation Checklist

Operations and Maintenance

Troubleshooting and Rollback

Source Links