Network topology tools reference

The topology tools build a complete map of your UniFi network — every device, every client, and every connection between them. You can retrieve the graph as structured data, export it to standard formats for visualization tools, or drill into the connections of a single device. All topology tools are read-only and derive their data by combining the device list and client list from the UniFi Integration API.

`get_network_topology`

Retrieves the complete network topology graph for a site. The response includes all adopted devices and connected clients as nodes, all uplink and client connections as edges, and summary statistics about the graph.

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

Parameters

string

required

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

boolean

default:"false"

When true, the tool calculates position coordinates for each node, which can be used to lay out a visual diagram. When false (the default), coordinates are omitted for a smaller response payload.

Response

string

The resolved site identifier used for the query.

string

ISO 8601 timestamp indicating when the topology was captured.

object[]

All devices and clients in the topology.

Show Node object fields

string

Unique node identifier (device ID or client ID from the UniFi API).

string

"device" for UniFi hardware; "client" for connected end devices.

string

Display name for the node.

string

MAC address.

string

IP address.

string

Device model string. Present for device nodes only.

string

ID of the device this node connects to upstream. null for the gateway.

number

Port index on the upstream device. May be null for wireless uplinks.

number

Number of hops from the gateway. 0 = directly connected to gateway.

number

1 = connected/online, 0 = disconnected/offline.

object[]

All edges in the topology graph.

Show Connection object fields

string

Unique identifier for this connection.

string

ID of the node at the source end.

string

ID of the node at the target end.

string

"uplink" for device-to-device links; "wired" or "wireless" for client connections.

number

Port index on the source device, if applicable.

number

Link speed in Mbps. May be null for wireless connections.

boolean

true for device-to-device uplinks; false for client connections.

string

"up" or "down".

number

Count of device nodes in the graph.

number

Count of client nodes in the graph.

number

Count of edges in the graph.

number

Maximum uplink depth across all device nodes. Indicates how many switch hops exist between the furthest device and the gateway.

Example response (abbreviated)

{
  "site_id": "default",
  "generated_at": "2026-04-22T10:00:00Z",
  "nodes": [
    {
      "node_id": "gw-001",
      "node_type": "device",
      "name": "UDM Pro",
      "mac": "aa:bb:cc:dd:ee:01",
      "ip": "192.168.1.1",
      "model": "UDM-Pro",
      "uplink_device_id": null,
      "uplink_depth": 0,
      "state": 1
    },
    {
      "node_id": "sw-001",
      "node_type": "device",
      "name": "Core Switch",
      "mac": "aa:bb:cc:dd:ee:02",
      "ip": "192.168.1.2",
      "model": "USW-Pro-24-POE",
      "uplink_device_id": "gw-001",
      "uplink_port": 1,
      "uplink_depth": 1,
      "state": 1
    }
  ],
  "connections": [
    {
      "connection_id": "conn_sw-001_uplink",
      "source_node_id": "sw-001",
      "target_node_id": "gw-001",
      "connection_type": "uplink",
      "source_port": 1,
      "speed_mbps": 10000,
      "is_uplink": true,
      "status": "up"
    }
  ],
  "total_devices": 8,
  "total_clients": 34,
  "total_connections": 42,
  "max_depth": 2,
  "has_coordinates": false
}

`export_topology`

Exports the network topology in a standard graph format as a formatted string. Use this tool when you want to load your topology into an external visualization or analysis tool.

result = await mcp.call_tool("export_topology", {
    "site_id": "default",
    "format": "graphml"
})

Parameters

string

required

The site identifier.

string

required

Export format. One of three values:

"json" — Full topology as a pretty-printed JSON string. Suitable for programmatic processing or archival.
"graphml" — XML-based GraphML format. Import into Gephi or yEd for visual network diagrams.
"dot" — Graphviz DOT language format. Render with dot, neato, or other Graphviz tools to produce SVG or PNG diagrams.

Response

Returns the topology data as a plain string in the requested format. The string can be written directly to a file or piped into a visualization tool.

JSON
GraphML (Gephi)
DOT (Graphviz)

json_str = await mcp.call_tool("export_topology", {
    "site_id": "default",
    "format": "json"
})
# Write to file
with open("topology.json", "w") as f:
    f.write(json_str)

graphml_str = await mcp.call_tool("export_topology", {
    "site_id": "default",
    "format": "graphml"
})
# Save and open in Gephi
with open("topology.graphml", "w") as f:
    f.write(graphml_str)

dot_str = await mcp.call_tool("export_topology", {
    "site_id": "default",
    "format": "dot"
})
# Save and render with Graphviz
with open("topology.dot", "w") as f:
    f.write(dot_str)
# Then run: dot -Tsvg topology.dot -o topology.svg

Format comparison

Format	Best for	Tools
`json`	Programmatic analysis, archival, feeding into dashboards	Python, jq, any JSON parser
`graphml`	Interactive visual exploration, community detection	Gephi, yEd, Cytoscape
`dot`	Static diagrams, documentation, quick rendering	Graphviz (`dot`, `neato`, `fdp`)

If you pass any value other than "json", "graphml", or "dot", the tool raises ValidationError. The format parameter is case-sensitive.

`get_device_connections`

Returns only the connection records that involve a specific device, or all connections if no device is specified. Use this tool when you want to understand what a particular switch or access point is connected to without processing the full topology graph.

result = await mcp.call_tool("get_device_connections", {
    "site_id": "default",
    "device_id": "sw-001"
})

Parameters

string

required

The site identifier.

string

The device’s unique identifier. When provided, only connections where the device appears as either the source or target are returned. When omitted or null, all connections in the topology are returned.

Response

Returns an array of connection objects in the same format as the connections array in get_network_topology.

[
  {
    "connection_id": "conn_sw-001_uplink",
    "source_node_id": "sw-001",
    "target_node_id": "gw-001",
    "connection_type": "uplink",
    "source_port": 1,
    "speed_mbps": 10000,
    "is_uplink": true,
    "status": "up"
  },
  {
    "connection_id": "conn_client_abc123",
    "source_node_id": "client-abc123",
    "target_node_id": "sw-001",
    "connection_type": "wired",
    "is_uplink": false,
    "status": "up"
  }
]

`get_port_mappings`

Returns a port-level view of which devices and clients are connected to each physical port on a specific device. This is particularly useful for auditing switch port usage.

result = await mcp.call_tool("get_port_mappings", {
    "site_id": "default",
    "device_id": "sw-001"
})

Parameters

string

required

The site identifier.

string

required

The device’s unique identifier. Typically a switch — access points and gateways may have fewer connections to map.

Response

string

The device that was queried.

object

A dictionary keyed by port index number. Each value describes what is connected to that port.

Show Port entry fields

string

Node ID of the device or client connected to this port.

string

"uplink", "wired", or "wireless".

number

Negotiated link speed. May be null if not reported.

string

"up" or "down".

Example response

{
  "device_id": "sw-001",
  "ports": {
    "1": {
      "connected_to": "gw-001",
      "connection_type": "uplink",
      "speed_mbps": 10000,
      "status": "up"
    },
    "3": {
      "connected_to": "ap-001",
      "connection_type": "wired",
      "speed_mbps": 1000,
      "status": "up"
    },
    "5": {
      "connected_to": "client-abc123",
      "connection_type": "wired",
      "speed_mbps": 1000,
      "status": "up"
    }
  }
}

`get_topology_statistics`

Returns a lightweight summary of the topology — device count, client count, connection count, and maximum network depth — without transferring the full node and edge data. Use this when you need a quick health check rather than the complete graph.

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

Parameters

string

required

The site identifier.

Response

string

The site that was queried.

number

Number of adopted devices in the topology.

number

Number of connected clients in the topology.

number

Total number of edges in the topology graph.

number

Maximum uplink depth. A value greater than 2 indicates devices more than two switch hops from the gateway, which may affect latency-sensitive applications.

string

ISO 8601 timestamp of when the underlying topology was captured.

Example response

{
  "site_id": "default",
  "total_devices": 8,
  "total_clients": 34,
  "total_connections": 42,
  "max_depth": 2,
  "generated_at": "2026-04-22T10:00:00Z"
}

get_topology_statistics builds a complete topology internally and then discards the node and edge data, returning only the summary. It makes the same number of API calls as get_network_topology, so it is most useful when you only need the summary numbers and want to avoid transmitting large node lists.

Overview

Read Operations

Write Operations

Security & Access

Operations

Network topology tools reference

`get_network_topology`

Parameters

Response

Example response (abbreviated)

`export_topology`

Parameters

Response

Format comparison

`get_device_connections`

Parameters

Response

`get_port_mappings`

Parameters

Response

Example response

`get_topology_statistics`

Parameters

Response

Example response

​get_network_topology

​Parameters

​Response

​Example response (abbreviated)

​export_topology

​Parameters

​Response

​Format comparison

​get_device_connections

​Parameters

​Response

​get_port_mappings

​Parameters

​Response

​Example response

​get_topology_statistics

​Parameters

​Response

​Example response

`get_network_topology`

Parameters

Response

Example response (abbreviated)

`export_topology`

Parameters

Response

Format comparison

`get_device_connections`

Parameters

Response

`get_port_mappings`

Parameters

Response

Example response

`get_topology_statistics`

Parameters

Response

Example response