Network query tools reference

The network query tools give you full visibility into how your UniFi site is segmented — which VLANs exist, how subnets are configured, and how traffic is distributed across networks. All four tools are read-only and can be called at any time without affecting your network configuration.

`list_vlans`

Returns all network configurations on a site. Despite the name, this tool returns every network — not just those with an explicit VLAN ID — because the local gateway API does not always populate vlan_id for every network type.

result = await mcp.call_tool("list_vlans", {
    "site_id": "default"
})

Parameters

string

required

The site identifier. Use "default" for single-site deployments.

number

default:"100"

Maximum number of networks to return.

number

default:"0"

Number of networks to skip. Use with limit for pagination across large site configurations.

Response

Returns an array of network objects.

Show Network object fields

string

Unique network identifier (_id from the UniFi API).

string

Network name as configured in UniFi Network.

string

Network purpose: corporate, guest, vlan-only, or wan.

number

VLAN tag number (1–4094). May be absent or null for the default LAN.

string

Subnet in CIDR notation, for example 192.168.10.0/24.

boolean

Whether the built-in DHCP server is active for this network.

Example response

[
  {
    "id": "507f191e810c19729de860ea",
    "name": "LAN",
    "purpose": "corporate",
    "vlan_id": 1,
    "ip_subnet": "192.168.1.0/24",
    "dhcpd_enabled": true
  },
  {
    "id": "507f191e810c19729de860eb",
    "name": "IoT",
    "purpose": "corporate",
    "vlan_id": 20,
    "ip_subnet": "192.168.20.0/24",
    "dhcpd_enabled": true
  }
]

`get_network_details`

Returns the full configuration record for a single network identified by its ID.

result = await mcp.call_tool("get_network_details", {
    "site_id": "default",
    "network_id": "507f191e810c19729de860ea"
})

Parameters

string

required

The site identifier.

string

required

The network’s unique identifier. Use list_vlans to discover network IDs.

Response

Returns a single network object with the same fields as list_vlans, plus any additional configuration fields stored for that network.

Example response

{
  "id": "507f191e810c19729de860ea",
  "name": "LAN",
  "purpose": "corporate",
  "vlan_id": 1,
  "ip_subnet": "192.168.1.0/24",
  "dhcpd_enabled": true
}

If the network ID does not exist on the site, the tool raises ResourceNotFoundError. Network IDs are site-scoped — an ID from one site is not valid on another.

`get_subnet_info`

Returns detailed subnet and DHCP configuration for a single network. This is more focused than get_network_details and is specifically useful when you need to inspect DHCP range, lease time, DNS servers, or gateway settings.

result = await mcp.call_tool("get_subnet_info", {
    "site_id": "default",
    "network_id": "507f191e810c19729de860ea"
})

Parameters

string

required

The site identifier.

string

required

The network’s unique identifier.

Response

string

The network identifier that was queried.

string

Network name.

string

Subnet in CIDR notation.

number

VLAN tag number. May be null for the default LAN.

boolean

Whether the UniFi DHCP server is enabled for this network.

string

First IP address in the DHCP lease range.

string

Last IP address in the DHCP lease range.

number

DHCP lease duration in seconds.

string

Primary DNS server address pushed to DHCP clients.

string

Secondary DNS server address.

string

Tertiary DNS server address.

string

Quaternary DNS server address.

string

Gateway IP address pushed to DHCP clients.

string

Local domain name pushed to DHCP clients, for example local.

Example response

{
  "network_id": "507f191e810c19729de860ea",
  "name": "LAN",
  "ip_subnet": "192.168.1.0/24",
  "vlan_id": 1,
  "dhcpd_enabled": true,
  "dhcpd_start": "192.168.1.100",
  "dhcpd_stop": "192.168.1.254",
  "dhcpd_leasetime": 86400,
  "dhcpd_dns_1": "8.8.8.8",
  "dhcpd_dns_2": "8.8.4.4",
  "dhcpd_dns_3": null,
  "dhcpd_dns_4": null,
  "dhcpd_gateway": "192.168.1.1",
  "domain_name": "local"
}

`get_network_statistics`

Returns traffic and client usage statistics aggregated per network for an entire site. Useful for identifying which VLANs are busiest and how many clients are on each segment.

result = await mcp.call_tool("get_network_statistics", {
    "site_id": "default"
})

Parameters

string

required

The site identifier. This tool returns statistics for all networks on the site.

Response

string

The site that was queried.

object[]

Array of per-network statistics objects.

Show Network statistics fields

string

Network identifier.

string

Network name.

number

VLAN tag number.

number

Number of active clients currently on this network segment.

number

Total bytes transmitted by all clients on this network.

number

Total bytes received by all clients on this network.

number

Combined transmit and receive bytes.

Example response

{
  "site_id": "default",
  "networks": [
    {
      "network_id": "507f191e810c19729de860ea",
      "name": "LAN",
      "vlan_id": 1,
      "client_count": 15,
      "total_tx_bytes": 10240000,
      "total_rx_bytes": 20480000,
      "total_bytes": 30720000
    },
    {
      "network_id": "507f191e810c19729de860eb",
      "name": "IoT",
      "vlan_id": 20,
      "client_count": 8,
      "total_tx_bytes": 2048000,
      "total_rx_bytes": 1024000,
      "total_bytes": 3072000
    }
  ]
}

Client counts in get_network_statistics are calculated from the active client table by matching each client’s vlan field to the network’s vlan_id. If you see zero clients on a network you know has devices, verify that the VLAN ID is correctly set on both the network and the switch ports.

Overview

Read Operations

Write Operations

Security & Access

Operations

Network query tools reference

`list_vlans`

Parameters

Response

Example response

`get_network_details`

Parameters

Response

Example response

`get_subnet_info`

Parameters

Response

Example response

`get_network_statistics`

Parameters

Response

Example response

​list_vlans

​Parameters

​Response

​Example response

​get_network_details

​Parameters

​Response

​Example response

​get_subnet_info

​Parameters

​Response

​Example response

​get_network_statistics

​Parameters

​Response

​Example response

`list_vlans`

Parameters

Response

Example response

`get_network_details`

Parameters

Response

Example response

`get_subnet_info`

Parameters

Response

Example response

`get_network_statistics`

Parameters

Response

Example response