Skip to main content
Glama

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.py

Option 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.py

Option 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-mcp

Or 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-stopped

Environment Variables

Variable

Default

Description

UNIFI_HOST

127.0.0.1

UniFi controller IP or hostname

UNIFI_PORT

11443

HTTPS port (11443 for self-hosted, 443 for cloud)

UNIFI_API_KEY

(required)

API key from Settings → Integrations

MCP_TRANSPORT

stdio

Transport: stdio | sse | streamable-http

MCP_PORT

8000

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

  1. Log in to your UniFi Network Application

  2. Go to Settings → Control Plane → Integrations

  3. Click Create API Key

  4. 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, set verify=True in server.py.

  • site_id defaults to "default" which resolves to your first site. Pass a site name or UUID for multi-site setups.

License

MIT

Available Tools

51 tools
unifi_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

    B3.2/5.0

    Scored across 51 tools

    Disambiguation3/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      An 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.
      31
      MIT
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Turns your UniFi Network Controller into programmable tools for querying and modifying network settings via MCP.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP 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.
      6
      Mozilla Public 2.0