Site query tools reference

The site query tools give you visibility into all UniFi sites your API key has access to. In single-site deployments you will typically deal with one site named "default", but these tools become essential in multi-site environments where you need to discover site identifiers before calling device or network tools. All three tools are read-only.

`list_sites`

Returns all sites accessible with your configured API key. The tool automatically selects the correct API endpoint based on whether you are using the local gateway or cloud API.

result = await mcp.call_tool("list_sites", {})

Parameters

number

default:"100"

Maximum number of sites to return.

number

default:"0"

Number of sites to skip for pagination across large multi-site organizations.

Response

Returns an array of site objects.

Show Site object fields

string

Unique site identifier. Pass this value as site_id in other tools.

string

Site name as configured in UniFi Site Manager.

string

Optional site description.

string

Internal reference string. Some sites are addressable by this value as well as by id or name.

Example response

[
  {
    "id": "default",
    "name": "Home",
    "desc": "Main home network"
  },
  {
    "id": "site-abc123",
    "name": "Office",
    "desc": "Corporate office location"
  }
]

`get_site_details`

Returns the full record for a single site. You can look up a site by its _id, by its name, or by its internalReference — the tool checks all three fields.

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

Parameters

string

required

The site identifier. Accepted values:

The site’s _id (for example, "507f1f77bcf86cd799439011")
The site’s name (for example, "Home")
The site’s internalReference string
"default" for the primary site on local gateway deployments

Response

Returns a single site object with the same fields as list_sites.

Example response

{
  "id": "default",
  "name": "Default Site",
  "desc": "Default site description"
}

If no site matches the provided site_id, the tool raises ResourceNotFoundError. Double-check the value against list_sites output if you receive this error.

`get_site_statistics`

Returns a comprehensive summary of site health — device counts by type, online/offline status, client counts by connection type, network count, and total bandwidth consumed across all clients.

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

Parameters

string

required

The site identifier.

Response

string

The site that was queried.

object

Device inventory summary.

Show Device fields

number

Total number of adopted devices on the site.

number

Number of devices with state 1 (connected).

number

Number of devices that are not responding.

number

Count of devices with type uap.

number

Count of devices with type usw.

number

Count of devices with type ugw, udm, or uxg.

object

Active client summary.

Show Client fields

number

Total active clients on the site.

number

Clients connected via Ethernet.

number

Clients connected via WiFi.

object

Show Network fields

number

Total number of configured networks on the site.

object

Aggregate bandwidth across all active clients.

Show Bandwidth fields

number

Total bytes transmitted by all clients.

number

Total bytes received by all clients.

number

Combined total bytes.

Example response

{
  "site_id": "default",
  "devices": {
    "total": 25,
    "online": 24,
    "offline": 1,
    "access_points": 10,
    "switches": 8,
    "gateways": 7
  },
  "clients": {
    "total": 42,
    "wired": 15,
    "wireless": 27
  },
  "networks": {
    "total": 5
  },
  "bandwidth": {
    "total_tx_bytes": 102400000,
    "total_rx_bytes": 204800000,
    "total_bytes": 307200000
  }
}

get_site_statistics gathers data from three separate API endpoints (devices, active clients, and networks) in a single call, making it the most efficient way to get a site health snapshot. Use it as a starting point before drilling into specific devices or clients.

Overview

Read Operations

Write Operations

Security & Access

Operations

`list_sites`

Parameters

Response

Example response

`get_site_details`

Parameters

Response

Example response

`get_site_statistics`

Parameters

Response

Example response

​list_sites

​Parameters

​Response

​Example response

​get_site_details

​Parameters

​Response

​Example response

​get_site_statistics

​Parameters

​Response

​Example response

`list_sites`

Parameters

Response

Example response

`get_site_details`

Parameters

Response

Example response

`get_site_statistics`

Parameters

Response

Example response