Unifi AP MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Unifi AP MCP list all access points"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Unifi AP MCP
MCP (Model Context Protocol) server for UniFi Network Controller — full API coverage for managing APs, clients, WLANs, firewall rules, VLANs, port forwards, and more.
Built with FastMCP and httpx. Supports both the UniFi Integration API v1 and the Legacy API.
Features
Devices — list, get stats (channel, power, uptime, memory, tx/rx)
Clients — connected clients, all-time history, block/unblock/kick, guest auth
WLANs — list, create, update (password, band, VLAN, guest mode), delete
Networks (VLANs) — list, create, update, delete
Firewall — rules (create/update/delete) + groups (address-group/port-group)
Port Forwards — list, create, update, delete
Static Routes — list
DPI Stats — per-client and site-level deep packet inspection
Traffic Reports — hourly/daily per site, AP, or user
Health & Sysinfo — subsystem status, controller version
Rogue APs — neighboring AP scan results
Vouchers — hotspot voucher list
Settings — all site settings
RADIUS Profiles — list
Related MCP server: UniFi Network MCP Server
Requirements
Python 3.11+
UniFi Network Application 8.x+ (self-hosted or UniFi Cloud Gateway)
API Key: Settings → Control Plane → Integrations → Create API Key
Installation
Option 1: Run directly with uv (recommended)
pip install uv # if not already installed
UNIFI_HOST=192.168.1.1 UNIFI_PORT=11443 UNIFI_API_KEY=your-api-key \
uvx --from git+https://github.com/haiduongacm/unifi-ap-mcp server.pyOption 2: Clone and run
git clone https://github.com/haiduongacm/unifi-ap-mcp.git
cd unifi-ap-mcp
uv venv && uv pip install -e .
UNIFI_HOST=192.168.1.1 \
UNIFI_PORT=11443 \
UNIFI_API_KEY=your-api-key \
uv run server.pyOption 3: Docker
docker build -t unifi-ap-mcp .
docker run -d \
-p 8001:8000 \
-e UNIFI_HOST=192.168.1.1 \
-e UNIFI_PORT=11443 \
-e UNIFI_API_KEY=your-api-key \
unifi-ap-mcpOr with docker-compose:
services:
unifi-network:
build: .
ports:
- "8001:8000"
environment:
MCP_TRANSPORT: streamable-http
UNIFI_HOST: 192.168.1.1
UNIFI_PORT: "11443"
UNIFI_API_KEY: ${UNIFI_API_KEY}
restart: unless-stoppedEnvironment Variables
Variable | Default | Description |
|
| UniFi controller IP or hostname |
|
| HTTPS port (11443 for self-hosted, 443 for cloud) |
| (required) | API key from Settings → Integrations |
|
| Transport: |
|
| Port when using HTTP transport |
MCP Client Configuration
Claude Desktop / Claude Code (mcp.json)
stdio mode:
{
"mcpServers": {
"unifi-network": {
"command": "uv",
"args": ["run", "/path/to/server.py"],
"env": {
"UNIFI_HOST": "192.168.1.1",
"UNIFI_PORT": "11443",
"UNIFI_API_KEY": "your-api-key"
}
}
}
}HTTP mode (after docker run or uv run with MCP_TRANSPORT=streamable-http):
{
"mcpServers": {
"unifi-network": {
"type": "http",
"url": "http://localhost:8001/mcp"
}
}
}Getting Your API Key
Log in to your UniFi Network Application
Go to Settings → Control Plane → Integrations
Click Create API Key
Copy the key — it is shown only once
The API key replaces username/password authentication. No session management needed.
Notes
TLS verification is disabled (
verify=False) to support self-signed certificates on self-hosted controllers. For production use behind a reverse proxy with a valid certificate, setverify=Trueinserver.py.site_iddefaults to"default"which resolves to your first site. Pass a site name or UUID for multi-site setups.
License
MIT
Available Tools
51 toolsunifi_authorize_guestA
Authorize a client for guest portal access by MAC address. minutes: duration in minutes (default 60). up_kbps / down_kbps: optional bandwidth limits. mb_limit: optional data cap in MB.
Inputs: mac (required), site_id, minutes, up_kbps, +2 more.
unifi_block_clientA
Block a client by MAC address — prevents it from connecting to any SSID on the site. Use unifi_unblock_client to reverse.
Inputs: mac (required), site_id.
unifi_client_actionB
Perform a guest-access action on a client. action: 'AUTHORIZE_GUEST_ACCESS' or 'UNAUTHORIZE_GUEST_ACCESS'.
Inputs: client_id (required), action (required), site_id.
unifi_create_firewall_groupC
Create a firewall group. group_type: 'address-group' | 'port-group' | 'ipv6-address-group'. group_members: list of IPs/CIDRs (address-group) or ports/ranges (port-group).
Inputs: name (required), group_type (required), group_members (required), site_id.
unifi_create_firewall_ruleC
Create a firewall rule. ruleset: 'WAN_IN'|'WAN_OUT'|'WAN_LOCAL'|'LAN_IN'|'LAN_OUT'|'LAN_LOCAL'|'GUEST_IN'|'GUEST_OUT'|'GUEST_LOCAL'. action: 'accept'|'drop'|'reject'. protocol: 'all'|'tcp'|'udp'|'tcp_udp'|'icmp'. src/dst: optional IP or network address. src_port/dst_port: optional port or range (e.g. '80' or '8080:8090').
Inputs: name (required), ruleset (required), action, protocol, +9 more.
unifi_create_networkB
Create a new network (VLAN). management must be 'GATEWAY' or 'VLAN_ONLY'. Example ipv4_configuration: {'hostIpAddress':'10.10.20.1','prefixLength':24,'dhcpConfiguration':{'mode':'SERVER','ipAddressRange':{'start':'10.10.20.100','stop':'10.10.20.200'},'leaseTimeSeconds':86400}}.
Inputs: name (required), management (required), site_id, vlan_id, +6 more.
unifi_create_port_forwardB
Create a port forwarding rule. protocol: 'tcp'|'udp'|'tcp_udp'. src_port / fwd_port: port numbers or ranges (e.g. '80', '8080:8090'). fwd: destination LAN IP address.
Inputs: name (required), fwd (required), fwd_port (required), src_port (required), +4 more.
unifi_create_wlanB
Create a new WLAN (SSID). security: 'open' | 'wpapsk' | 'wpa2' | 'wpa3'. passphrase required unless security='open'. wlan_band: '2g' | '5g' | 'both'. vlan_id: tag clients into a specific VLAN. is_guest: True marks this as a guest network.
Inputs: name (required), security, passphrase, site_id, +7 more.
unifi_delete_firewall_groupC
Delete a firewall group by its _id.
Inputs: group_id (required), site_id.
unifi_delete_firewall_ruleB
Delete a firewall rule by its _id.
Inputs: rule_id (required), site_id.
unifi_delete_networkB
Delete a network by ID. System-defined networks cannot be deleted.
Inputs: network_id (required), site_id.
unifi_delete_port_forwardC
Delete a port forwarding rule by its _id.
Inputs: forward_id (required), site_id.
unifi_delete_wlanB
Delete a WLAN by its _id. This removes the SSID from all APs.
Inputs: wlan_id (required), site_id.
unifi_get_all_usersB
Get all known clients (connected + historical) for a site. Includes first-seen/last-seen timestamps, total data usage, hostname, OUI. within: limit to clients seen in the last N hours (optional).
Inputs: site_id, within.
unifi_get_clientB
Get details for a single client by client ID (Integration API).
Inputs: client_id (required), site_id.
unifi_get_client_statsA
Get detailed stats for currently connected clients (legacy API). Richer than unifi_list_clients — includes signal strength, tx/rx rate, channel, SSID, noise, satisfaction score, data usage.
Inputs: site_id.
unifi_get_deviceB
Get full details for a single device by its ID (Integration API).
Inputs: device_id (required), site_id.
unifi_get_device_statsA
Get detailed device statistics from the legacy API. Richer than unifi_list_devices — includes uptime, load, memory, radio channel/power, tx/rx bytes, client counts per radio band. mac: optional filter to a specific device MAC address.
Inputs: site_id, mac.
unifi_get_dpi_statsB
Get Deep Packet Inspection statistics per client. Returns tx/rx bytes and packet counts broken down by application category.
Inputs: site_id.
unifi_get_healthB
Get health status for all subsystems: wlan, wan, www, lan, vpn. Returns client counts, AP counts, and per-subsystem status (ok/warning/error).
Inputs: site_id.
unifi_get_networkA
Get full details for a single network. Returns VLAN ID, isolation, internet access, mDNS, IPv4 config (subnet, DHCP range, lease time).
Inputs: network_id (required), site_id.
unifi_get_rogue_apsA
List rogue / neighboring access points detected by your APs. Returns SSID, BSSID, channel, signal strength, security type, and detecting AP.
Inputs: site_id.
unifi_get_site_dpi_statsC
Get site-level DPI statistics aggregated across all clients.
Inputs: site_id.
unifi_get_sysinfoB
Get system information for the site: controller version, build, timezone, data retention settings, update status.
Inputs: site_id.
unifi_get_traffic_reportA
Get historical traffic statistics. report_type: 'daily.site' | 'hourly.site' | 'daily.ap' | 'hourly.ap' | 'daily.user' | 'hourly.user'. Returns bytes sent/received and number of clients per interval.
Inputs: report_type, site_id.
unifi_get_wlanA
Get details for a single WLAN by its _id.
Inputs: wlan_id (required), site_id.
unifi_kick_clientA
Force-disconnect (kick) a wireless client by MAC address. The client will attempt to reconnect immediately. mac: client MAC address (e.g. 'aa:bb:cc:dd:ee:ff').
Inputs: mac (required), site_id.
unifi_list_clientsA
List connected clients for a site (Integration API). Returns name, MAC, IP, type, connected-at, uplink device. Filters: type='WIRELESS'|'WIRED', uplink_device_id. Pagination: offset, limit (default 25).
Inputs: site_id, type, uplink_device_id, offset, +1 more.
unifi_list_devicesA
List adopted devices (APs, switches, gateways) for a site via Integration API. Returns name, MAC, model, state (ONLINE/OFFLINE), IP, firmware version. Filters: only_online=True, model string (e.g. 'U7Pro'). site_id accepts 'default', UUID, or display name.
Inputs: site_id, only_online, model.
unifi_list_firewall_groupsC
List firewall groups (address/port sets used in firewall rules).
Inputs: site_id.
unifi_list_firewall_rulesC
List all firewall rules on the site.
Inputs: site_id.
unifi_list_known_clientsA
List all known client records (persistent user database). Returns hostname, MAC, IP, notes, is_blocked, is_guest, first_seen, last_seen, data usage. This is different from unifi_get_client_stats which shows only currently connected clients.
Inputs: site_id.
unifi_list_networksB
List all networks (VLANs) for a site. Returns id, name, VLAN ID, management type, enabled state.
Inputs: site_id.
unifi_list_port_forwardsC
List all port forwarding rules on the site.
Inputs: site_id.
unifi_list_port_profilesB
List switch port profiles (port configs) for the site.
Inputs: site_id.
unifi_list_radius_profilesB
List RADIUS profiles for a site (read-only via Integration API).
Inputs: site_id.
unifi_list_routesC
List static routes configured on the site.
Inputs: site_id.
unifi_list_settingsA
List all site settings grouped by key (super_identity, country, locale, mgmt, connectivity, guest_access, ntp, radius, rsyslog, snmp, etc.).
Inputs: site_id.
unifi_list_sitesA
List all UniFi sites on this controller. Returns site UUIDs, names, and internal references.
Inputs: no named parameters.
unifi_list_vouchersC
List hotspot vouchers on the site.
Inputs: site_id.
unifi_list_wlansB
List all WLANs (SSIDs) configured on the site. Returns name, security, enabled state, VLAN, band, guest mode, user-group.
Inputs: site_id.
unifi_restart_deviceA
Restart (reboot) an AP or switch by its MAC address. The device will be offline for ~60 seconds while rebooting.
Inputs: mac (required), site_id.
unifi_unauthorize_guestB
Revoke guest portal authorization for a client by MAC address.
Inputs: mac (required), site_id.
unifi_unblock_clientC
Unblock a previously blocked client by MAC address.
Inputs: mac (required), site_id.
unifi_update_firewall_groupA
Update a firewall group by its _id (add/remove members).
Inputs: group_id (required), group_members (required), site_id, name.
unifi_update_firewall_ruleA
Update a firewall rule by its _id. Fetches current state and merges your changes.
Inputs: rule_id (required), site_id, enabled, action, +1 more.
unifi_update_known_clientC
Update a known client record by its _id. Common uses: set a friendly name (note), block/unblock, assign fixed IP. blocked: True to block the client at the network level.
Inputs: client_id (required), site_id, name, note, +3 more.
unifi_update_networkB
Update an existing network. Fetches current state, merges your changes, and PUTs back. management is required ('GATEWAY' or 'VLAN_ONLY'). System-defined networks can be updated but not deleted.
Inputs: network_id (required), management (required), site_id, name, +7 more.
unifi_update_port_forwardC
Update a port forwarding rule by its _id.
Inputs: forward_id (required), site_id, enabled, fwd, +3 more.
unifi_update_wlanA
Update a WLAN by its _id. Fetches current config and merges your fields. Common uses: change password, enable/disable SSID, change band, toggle guest mode.
Inputs: wlan_id (required), site_id, name, enabled, +5 more.
unifi_upgrade_deviceA
Trigger a firmware upgrade on an AP or switch by its MAC address. Only upgrades if a newer firmware is available. Device will reboot after upgrade.
Inputs: mac (required), site_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 51 tools
While most tools are distinct per resource, client management has significant overlap (e.g., unifi_authorize_guest vs unifi_client_action with AUTHORIZE_GUEST; unifi_get_all_users vs unifi_list_known_clients; unifi_block_client and unifi_unblock_client vs unifi_update_known_client's block option). This could confuse an agent.
All tools follow a consistent 'unifi_verb_noun' pattern (e.g., unifi_create_firewall_group, unifi_delete_wlan). Verbs are clear and uniform (list, get, create, delete, update, etc.), making the set predictable.
51 tools is high. While the domain (UniFi network management) is complex, many tools could be consolidated (e.g., client actions). The count feels slightly bloated but still manageable with good grouping.
Covers most essential resources (networks, WLANs, firewall, clients, devices) with CRUD. Missing: ability to update device settings or create/delete sites. Minor gaps that agents can work around.
Related MCP Connectors
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
The official MCP Server for the Mux API
Secure and manage MCP servers through the Speakeasy AI Control Plane from your agent.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceAn MCP server for self-hosted UniFi gateway management, providing tools for devices, networks, WiFi, firewall rules, switch port profiles, connected clients, and a one-shot IoT network creation with rollback.31MIT
- -licenseNot gradedqualityNot gradedmaintenanceTurns your UniFi Network Controller into programmable tools for querying and modifying network settings via MCP.-
- AlicenseNot gradedqualityBmaintenanceMCP server for UniFi Network Controller enabling AI assistants to manage UniFi infrastructure via natural language. It supports firewall rules, IPv6, and uses lazy/eager tool modes to minimize context usage.6Mozilla Public 2.0
- AlicenseNot gradedqualityCmaintenanceMCP server and CLI for UniFi Network controllers: clients, devices, WLANs, firewall, and health over stdio or streamable HTTP, with auth.5AGPL 3.0