unifi-network-engineer

description	Use when deploying, managing, maintaining, or troubleshooting Ubiquiti UniFi networks. Covers switch/AP/gateway config, firewall policies, WLANs, VLANs, VPN, port profiles, RF tuning, and monitoring via the UniFi MCP.
name	unifi-network-engineer
triggers	["unifi configuration","ubiquiti network management","switch port configuration","firewall policy","wlan ssid setup","vlan network creation","vpn setup unifi","unifi troubleshooting","unifi monitoring"]
version	1.0.0
author	Hermes Agent
license	MIT
metadata	{"hermes":{"tags":["unifi","networking","ubiquiti","devops","infrastructure","firewall","switch","wlan","vpn"],"related_skills":["muninndb"]}}

UniFi Network Engineering

Provides subject-matter expertise for deploying, managing, and maintaining UniFi networks. All operations go through the unifi-network MCP server — never use direct HTTP/curl against the UniFi controller.

When using any create or update tool that requires confirmation, always fetch the current state first with the corresponding list or get tool, present a clear summary of what will change, then proceed only after user confirmation.

When to Use

• Setting up a new network, VLAN, or SSID
• Configuring switch ports (access/trunk, PoE, port profiles, aggregation)
• Creating or modifying firewall policies and groups
• Deploying VPN servers or clients (WireGuard, OpenVPN, L2TP)
• Troubleshooting client connectivity, performance, or RF issues
• Monitoring network health, alarms, events, and device stats
• Managing firmware upgrades, backups, and device lifecycle
• Configuring guest networks, hotspots, and vouchers
• Implementing QoS, traffic routing, or content filtering
• Managing DNS records, DHCP scopes, and static IP assignments

Don't use for: Home Assistant operations (use the ha-mcp server), general server management, or anything outside the UniFi Network Application scope.

Tool Reference (unifi-network MCP)

All tools are prefixed mcp_unifi_network_ in the Hermes tool namespace. Key categories:

Discovery & Monitoring

Tool	Purpose
unifi_get_dashboard	Site health summary (device/client counts, ISP status)
unifi_get_network_health	Per-subsystem health (WAN, LAN, WLAN, VPN)
unifi_get_system_info	Controller version, uptime, CPU/memory, updates
unifi_list_alarms	Active security alerts and connectivity issues
unifi_list_events	Event log (connects, disconnects, config changes)
unifi_recent_events	Real-time events from WebSocket buffer (fast, no API call)
unifi_get_speedtest_results	Historical speedtest results
unifi_get_anomalies	Network anomaly detection events

Clients

Tool	Purpose
unifi_list_clients	Connected clients with MAC, name, IP, signal, status
unifi_get_client_details	Full client object (DHCP, stats, signal, fixed IP)
unifi_get_client_wifi_details	Detailed WiFi stats (signal, rates, retries, roam)
unifi_lookup_by_ip	Quick IP-to-client lookup
unifi_rename_client	Set a client's friendly name
unifi_set_client_ip_settings	Fixed IP / DHCP reservation + local DNS
unifi_block_client / unifi_unblock_client	Block/unblock a device by MAC
unifi_forget_client	Remove client record from controller
unifi_force_reconnect_client	Kick a client to force reconnection
unifi_list_blocked_clients	View currently blocked devices
unifi_authorize_guest / unifi_unauthorize_guest	Manage guest network access

Devices (Switches, APs, Gateways, PDUs)

Tool	Purpose
unifi_list_devices	Inventory with model, firmware, IP, uplink, status
unifi_get_device_details	Full device raw object (radios, ports, system stats)
unifi_get_device_stats	Historical traffic time-series
unifi_rename_device	Set a device's friendly name
unifi_reboot_device	Reboot a device
unifi_upgrade_device	Initiate firmware upgrade
unifi_force_provision_device	Push config from controller to device (fix drift)
unifi_toggle_device	Enable/disable a device (stops traffic)
unifi_locate_device	Blink device LED for physical identification
unifi_set_device_led	Override LED state per-device
unifi_set_site_leds	Toggle all device LEDs site-wide
unifi_adopt_device	Adopt a pending device by MAC
unifi_get_pdu_outlets	PDU outlet states
unifi_set_outlet_state	Toggle PDU outlet on/off

Switch Port Management

Tool	Purpose
unifi_get_switch_ports	Port assignments, names, PoE mode, profiles
unifi_get_port_stats	Live port stats (link speed, PoE draw, errors)
unifi_get_switch_capabilities	Max ACLs, VLANs, aggregation/mirror sessions
unifi_get_lldp_neighbors	LLDP neighbor table
unifi_list_port_profiles	Available port profiles
unifi_get_port_profile_details	Full profile (VLAN, isolation, PoE, STP, 802.1X)
unifi_create_port_profile	Create a new port profile
unifi_update_port_profile	Update a port profile
unifi_delete_port_profile	Delete a port profile
unifi_set_switch_port_profile	Assign profile to a specific port
unifi_configure_port_aggregation	Configure LACP/LAG on switch
unifi_configure_port_mirror	Set up port mirroring for packet capture
unifi_power_cycle_port	Power cycle PoE on a port (reboot powered device)
unifi_set_jumbo_frames	Toggle jumbo frames
unifi_update_switch_stp	Configure STP priority and version

Wireless (WLANs & AP Groups)

Tool	Purpose
unifi_list_wlans	List all configured SSIDs
unifi_get_wlan_details	Full WLAN config
unifi_create_wlan	Create new SSID
unifi_update_wlan	Modify SSID (security, band, MAC filter, schedule)
unifi_delete_wlan	Delete an SSID (disconnects all clients)
unifi_toggle_wlan	Enable/disable an SSID
unifi_list_ap_groups	AP group config
unifi_get_ap_group_details	AP group details (members, WLANs)
unifi_create_ap_group	Create AP group
unifi_update_ap_group	Modify AP group
unifi_delete_ap_group	Delete AP group
unifi_get_device_radio	Radio config per AP band
unifi_update_device_radio	Channel, TX power, width, min RSSI, 802.11k/v
unifi_trigger_rf_scan	Start RF spectrum scan (5-10 min)
unifi_get_rf_scan_results	Per-channel interference + utilization
unifi_list_available_channels	Allowed channels for site's regulatory domain
unifi_list_rogue_aps	Neighboring/rogue APs detected

Networks & VLANs

Tool	Purpose
unifi_list_networks	All networks with subnet, VLAN ID, DHCP settings
unifi_get_network_details	Full network config
unifi_create_network	Create new LAN/VLAN
unifi_update_network	Modify network (DHCP, DNS, VLAN, isolation)
unifi_create_dns_record	Static DNS A/AAAA/CNAME/MX/TXT/SRV record
unifi_list_dns_records	All static DNS records
unifi_get_dns_record_details	Single DNS record detail
unifi_update_dns_record	Modify a DNS record
unifi_delete_dns_record	Remove a DNS record

Firewall

Tool	Purpose
unifi_list_firewall_policies	All zone-based firewall policies
unifi_get_firewall_policy_details	Full policy config
unifi_create_firewall_policy	Create ALLOW/BLOCK/REJECT policy (zone-based)
unifi_update_firewall_policy	Modify a firewall policy
unifi_delete_firewall_policy	Delete a policy (WARNING: may break connectivity)
unifi_toggle_firewall_policy	Enable/disable a policy
unifi_list_firewall_groups	Address and port groups
unifi_get_firewall_group_details	Full group config
unifi_create_firewall_group	Create address or port group
unifi_update_firewall_group	Modify a firewall group
unifi_delete_firewall_group	Delete a group (may break policies)
unifi_list_firewall_zones	Available firewall zones (V2)
unifi_list_acl_rules	MAC ACL rules (Layer 2)
unifi_get_acl_rule_details	Single ACL rule detail
unifi_create_acl_rule	Create MAC ACL rule
unifi_update_acl_rule	Modify ACL rule
unifi_delete_acl_rule	Delete ACL rule

Port Forwards

Tool	Purpose
unifi_list_port_forwards	All port forwarding rules
unifi_get_port_forward	Single rule detail
unifi_create_port_forward / unifi_create_simple_port_forward	Create new rule
unifi_update_port_forward	Modify a rule
unifi_toggle_port_forward	Enable/disable a rule

VPN

Tool	Purpose
unifi_list_vpn_servers	All VPN server configs
unifi_get_vpn_server_details	Single server detail
unifi_update_vpn_server_state	Enable/disable a VPN server
unifi_list_vpn_clients	All VPN client configs
unifi_get_vpn_client_details	Single client detail
unifi_update_vpn_client_state	Enable/disable a VPN client

Traffic Management (QoS, OON, Routing, Content Filtering)

Tool	Purpose
unifi_list_oon_policies	Internet access schedules, app blocking, bandwidth
unifi_get_oon_policy_details	Full OON policy detail
unifi_create_oon_policy	Create new OON policy
unifi_update_oon_policy	Modify OON policy
unifi_toggle_oon_policy	Enable/disable OON policy
unifi_delete_oon_policy	Remove OON policy (removes auto-generated rules)
unifi_list_qos_rules	All QoS rules
unifi_get_qos_rule_details	Single QoS rule detail
unifi_create_qos_rule / unifi_create_simple_qos_rule	Create QoS rule
unifi_update_qos_rule	Modify QoS rule
unifi_toggle_qos_rule_enabled	Enable/disable QoS rule
unifi_list_traffic_routes	Policy-based routing rules
unifi_get_traffic_route_details	Single traffic route detail
unifi_update_traffic_route	Modify/enable/disable traffic route
unifi_toggle_traffic_route	Enable/disable a traffic route
unifi_list_content_filters	DNS content filtering profiles
unifi_get_content_filter_details	Full content filter config
unifi_update_content_filter	Modify categories, safe search, allow/block lists
unifi_delete_content_filter	Delete content filter profile
unifi_list_client_groups	Network member groups (for OON/firewall)
unifi_get_client_group_details	Single group detail
unifi_create_client_group	Create new client group
unifi_update_client_group	Modify client group
unifi_delete_client_group	Delete client group

Routing

Tool	Purpose
unifi_list_routes	All user-defined static routes
unifi_get_route_details	Single route detail
unifi_create_route	Create static route
unifi_update_route	Modify static route
unifi_list_active_routes	Current routing table (including system routes)

Hotspot & Guest Access

Tool	Purpose
unifi_list_vouchers	All hotspot vouchers
unifi_get_voucher_details	Single voucher detail
unifi_create_voucher	Create voucher(s) with time/bandwidth/data limits
unifi_revoke_voucher	Revoke a voucher by ID
unifi_list_usergroups	Bandwidth profiles
unifi_get_usergroup_details	Single user group detail
unifi_create_usergroup	Create bandwidth profile
unifi_update_usergroup	Modify bandwidth limits

Backup & System

Tool	Purpose
unifi_create_backup	Create controller config backup
unifi_list_backups	List available backups
unifi_delete_backup	Delete a backup file
unifi_get_autobackup_settings	Current auto-backup config
unifi_update_autobackup_settings	Modify auto-backup schedule/retention
unifi_get_site_settings	Site config (country, timezone)
unifi_get_snmp_settings	Current SNMP config
unifi_update_snmp_settings	Enable/disable SNMP, set community string

DPI & Traffic Stats

Tool	Purpose
unifi_get_dpi_stats	DPI categories and restrictions
unifi_get_site_dpi_traffic	Real bandwidth usage per application
unifi_get_client_dpi_traffic	Per-client DPI data
unifi_list_dpi_applications	Available DPI app IDs
unifi_list_dpi_categories	DPI category list
unifi_get_top_clients	Clients by total bandwidth usage

Common Workflows

VLAN Deployment

# 1. Create the network
unifi_create_network(name="iot", purpose="corporate",
    ip_subnet="10.0.20.1/24", vlan=20, dhcpd_start="10.0.20.10",
    dhcpd_stop="10.0.20.200", dhcpd_enabled=True)

# 2. Create port profile for the VLAN
unifi_create_port_profile(name="IoT Access", forward="native",
    native_networkconf_id="<network_id>")

# 3. Assign profile to switch ports
unifi_set_switch_port_profile(mac="<switch_mac>",
    port_idx=5, profile_id="<profile_id>")

SSID with Security Best Practices

unifi_create_wlan(name="Corporate", x_passphrase="<strong-password>",
    security="wpapsk", wpa3_support=True, wpa3_transition=False,
    pmf_mode="required", fast_roaming_enabled=True,
    wlan_band="both", hide_ssid=False)

Guest Network with Hotspot

# 1. Create guest network
unifi_create_network(name="Guest", purpose="guest",
    ip_subnet="10.0.99.1/24", vlan=99)

# 2. Create guest SSID
unifi_create_wlan(name="Guest-WiFi", security="open",
    guest_policy=True, networkconf_id="<network_id>")

# 3. Create vouchers
unifi_create_voucher(expire_number=24, expire_unit="hours",
    quota=1, count=20)

Firewall: Block IoT to Corporate LAN

# Create address group for IoT subnet
unifi_create_firewall_group(name="IoT-Subnet",
    group_type="address-group",
    group_members=["10.0.20.0/24"])

# Create BLOCK policy (zone-based V2)
unifi_create_firewall_policy(name="Block IoT to Corp",
    action="BLOCK",
    source={"zone_id": "<lan_zone>",
            "matching_target": "NETWORK",
            "matching_target_type": "OBJECT",
            "network_ids": ["<iot_network_id>"]},
    destination={"zone_id": "<lan_zone>",
                 "matching_target": "NETWORK",
                 "matching_target_type": "OBJECT",
                 "network_ids": ["<corp_network_id>"]})

Troubleshooting a Slow Client

# 1. Identify the client
client = unifi_lookup_by_ip("192.168.1.50")

# 2. Get detailed WiFi stats
wifi = unifi_get_client_wifi_details(client["mac"])

# Check RSSI (aim for > -67 dBm), retry rate, channel utilization,
# roam count, and which AP/band it's connected to.

# 3. Check the AP's radio and channel
radio = unifi_get_device_radio(ap_mac)

# 4. Scan for interference
unifi_trigger_rf_scan(ap_mac)
# Wait 5-10 min, then:
scan = unifi_get_rf_scan_results(ap_mac)

Common Pitfalls

1. Trying to set switch port profile without fetching current overrides first. unifi_set_switch_port_profile sends ALL port overrides as a full replacement — missing ports revert to defaults. Always call unifi_get_switch_ports first to get the full override array, modify the target port, then send the complete array back.

2. Creating a firewall group without knowing its type is immutable. group_type (address-group, ipv6-address-group, port-group) cannot be changed after creation. Double-check upfront.

3. MAC ACL rules affect Layer 2 communication within a VLAN. Removing an ALLOW rule may block device communication unexpectedly. Removing a BLOCK rule may open access you intended to restrict.

4. Port aggregation requires consecutive same-speed ports. Most switches support up to 8 aggregate sessions. The master port gets op_mode='aggregate', and member ports must be removed from the overrides array.

5. RF scans take 5-10 minutes. Trigger a scan, wait, then poll for results. Some APs briefly go off-channel during scan.

6. OON policy QOS and route fields must be full nested dicts. The list endpoint returns flattened booleans (qos_enabled, route_enabled), but create and update require the full nested structure. Use unifi_get_oon_policy_details on an existing policy as a template.

7. Content filter profiles can only be created via the UniFi UI. The API only supports list, update, and delete.

8. DPI stats endpoint may not be populated on newer UniFi OS versions. For IPS/IDS threats, check traffic flows instead.

9. Deleting a firewall policy, OON policy, or WLAN is destructive. Policies auto-generate firewall rules — deleting the parent policy removes all child rules. Always present a summary of impact before proceeding.

10. Static DNS records with an empty MAC list in ACL rules match any device. Be explicit with source/destination MAC lists to avoid unintended matches.

Verification Checklist

• Network/VLAN created and DHCP handing out addresses in the correct range
• SSID broadcasts and clients can connect with correct security (WPA3/PMF if configured)
• Switch port has the expected profile, PoE state, and VLAN assignment
• Firewall policy is in the correct position (order matters) and traffic flows as expected
• Port forward/ACL rule is active and accessible from outside (test with a port check)
• VPN tunnel established and traffic routes through correctly
• DNS records resolve from internal clients
• Backup created before making destructive changes
• Device status shows "online" after provisioning/adoption
• Alarms and events show expected activity without unexpected errors
• Content filters / OON schedules / QoS rules applying to the correct targets