Device query tools reference

The device query tools let you inspect every UniFi device on a site — access points, switches, gateways, and any device awaiting adoption. These tools are read-only and safe to call at any time. All of them accept a site_id to scope the request to a specific site; use "default" for single-site installations.

`list_devices_by_type`

Returns all devices on a site that match a given device type string. This is the primary way to list devices filtered to a specific hardware category.

result = await mcp.call_tool("list_devices_by_type", {
    "site_id": "default",
    "device_type": "uap"
})

Parameters

string

required

The site identifier. Use "default" for single-site deployments or the site’s internal ID for multi-site setups.

string

required

Device type filter string. Matched against the type field and the model field. Common values:

uap — UniFi access points
usw — UniFi switches
ugw — UniFi Security Gateways
udm — UniFi Dream Machines
uxg — UniFi Express Gateways

number

default:"100"

Maximum number of devices to return.

number

default:"0"

Number of devices to skip before returning results. Use with limit for pagination.

Response

Returns an array of device objects.

Show Device object fields

string

Unique device identifier (_id from the UniFi API).

string

Human-readable device name as set in UniFi Network.

string

Device model code, for example U6-LR or USW-Pro-24-POE.

string

Device category: uap, usw, ugw, udm, or uxg.

string

Device MAC address in colon-separated format.

string

Current IP address of the device.

number

Connection state. 1 means the device is online; 0 means offline.

number

Device uptime in seconds.

string

Firmware version string.

Example response

[
  {
    "id": "507f1f77bcf86cd799439011",
    "name": "Living Room AP",
    "model": "U6-LR",
    "type": "uap",
    "mac": "aa:bb:cc:dd:ee:ff",
    "ip": "192.168.2.100",
    "state": 1,
    "uptime": 86400,
    "version": "6.5.55.14277"
  }
]

`get_device_details`

Returns the full configuration and status record for a single device identified by its ID.

result = await mcp.call_tool("get_device_details", {
    "site_id": "default",
    "device_id": "507f1f77bcf86cd799439011"
})

Parameters

string

required

The site identifier.

string

required

The device’s unique identifier (_id from the UniFi API). Use list_devices_by_type or search_devices to find a device’s ID.

Response

Returns a single device object with the same fields as list_devices_by_type, plus any additional fields present in the UniFi API response for that device.

Example response

{
  "id": "507f1f77bcf86cd799439011",
  "name": "Living Room AP",
  "model": "U6-LR",
  "type": "uap",
  "mac": "aa:bb:cc:dd:ee:ff",
  "ip": "192.168.2.100",
  "state": 1,
  "uptime": 86400,
  "version": "6.5.55.14277"
}

If the device ID is not found on the site, the tool raises ResourceNotFoundError. Make sure the device_id belongs to the same site as site_id.

`get_device_statistics`

Returns real-time performance statistics for a single device: CPU usage, memory usage, throughput counters, and uptime.

result = await mcp.call_tool("get_device_statistics", {
    "site_id": "default",
    "device_id": "507f1f77bcf86cd799439011"
})

Parameters

string

required

The site identifier.

string

required

The device’s unique identifier.

Response

string

The device identifier that was queried.

number

Device uptime in seconds.

number

CPU utilization percentage (0–100). May be null if not reported by the device.

number

Memory utilization percentage (0–100). May be null if not reported by the device.

number

Total bytes transmitted since last reset.

number

Total bytes received since last reset.

number

Combined total bytes (tx_bytes + rx_bytes).

number

Current connection state. 1 = online, 0 = offline.

number

Number of hops from the gateway. 0 indicates the device is directly connected to the gateway.

Example response

{
  "device_id": "507f1f77bcf86cd799439011",
  "uptime": 86400,
  "cpu": 15,
  "mem": 42,
  "tx_bytes": 1024000000,
  "rx_bytes": 2048000000,
  "bytes": 3072000000,
  "state": 1,
  "uplink_depth": 0
}

`search_devices`

Searches all devices on a site by name, MAC address, IP address, or model string. The search is case-insensitive and matches partial strings.

result = await mcp.call_tool("search_devices", {
    "site_id": "default",
    "query": "office"
})

Parameters

string

required

The site identifier.

string

required

The search string. Matched against device name, mac, ip, and model fields. Partial matches are returned.

number

default:"100"

Maximum number of results to return.

number

default:"0"

Number of results to skip for pagination.

Response

Returns an array of device objects matching the query, in the same format as list_devices_by_type.

result = await mcp.call_tool("search_devices", {
    "site_id": "default",
    "query": "office"
})

result = await mcp.call_tool("search_devices", {
    "site_id": "default",
    "query": "aa:bb:cc"
})

result = await mcp.call_tool("search_devices", {
    "site_id": "default",
    "query": "U6-LR"
})

`list_pending_devices`

Returns devices that are visible on the network but have not yet been adopted into the site. Use this to discover new hardware before calling adopt_device.

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

Parameters

string

required

The site identifier.

number

default:"100"

Maximum number of pending devices to return.

number

default:"0"

Number of results to skip for pagination.

Response

Returns an array of device objects for unadopted hardware. Fields are the same as other device tools, though some fields may be absent for devices that haven’t been fully provisioned.

After reviewing pending devices with this tool, you can adopt them using the adopt_device write tool. Remember to pass confirm=True when adopting.

Overview

Read Operations

Write Operations

Security & Access

Operations

`list_devices_by_type`

Parameters

Response

Example response

`get_device_details`

Parameters

Response

Example response

`get_device_statistics`

Parameters

Response

Example response

`search_devices`

Parameters

Response

`list_pending_devices`

Parameters

Response

​list_devices_by_type

​Parameters

​Response

​Example response

​get_device_details

​Parameters

​Response

​Example response

​get_device_statistics

​Parameters

​Response

​Example response

​search_devices

​Parameters

​Response

​list_pending_devices

​Parameters

​Response

`list_devices_by_type`

Parameters

Response

Example response

`get_device_details`

Parameters

Response

Example response

`get_device_statistics`

Parameters

Response

Example response

`search_devices`

Parameters

Response

`list_pending_devices`

Parameters

Response