get_clients
Retrieve all currently connected clients on a UniFi network to monitor active devices and manage network access. Optionally include offline clients for historical analysis.
Instructions
Get all currently connected clients on the UniFi network
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| include_offline | No | Include offline/historical clients |
Implementation Reference
- src/unifi_mcp/server.py:178-184 (handler)The main handler logic for the 'get_clients' MCP tool within the call_tool function. It handles the tool invocation by checking the 'include_offline' parameter, fetching clients using UniFiClient methods, formatting them, and returning as TextContent.
case "get_clients": include_offline = arguments.get("include_offline", False) if include_offline: clients = await client.get_all_clients() else: clients = await client.get_clients() return [TextContent(type="text", text=format_clients(clients))] - src/unifi_mcp/server.py:45-59 (schema)Input schema definition for the 'get_clients' tool, including the optional 'include_offline' boolean parameter, as returned by list_tools().
Tool( name="get_clients", description="Get all currently connected clients on the UniFi network", inputSchema={ "type": "object", "properties": { "include_offline": { "type": "boolean", "description": "Include offline/historical clients", "default": False, } }, "required": [], }, ), - src/unifi_mcp/server.py:16-17 (registration)Registration of all tools including 'get_clients' via the @server.list_tools() decorator on the list_tools function.
@server.list_tools() async def list_tools() -> list[Tool]: - Low-level helper method in UniFiClient that fetches currently connected clients ('sta' endpoint) from the UniFi controller API.
async def get_clients(self) -> list[dict[str, Any]]: """Get all currently connected clients. Returns: List of client dictionaries. """ return await self._request("GET", "/api/s/{site}/stat/sta") - src/unifi_mcp/server.py:275-304 (helper)Helper function to format the list of clients into a human-readable string, used by the tool handler.
def format_clients(clients: list[dict[str, Any]]) -> str: """Format client list for display.""" if not clients: return "No clients found." lines = [f"Found {len(clients)} client(s):\n"] for c in clients: hostname = c.get("hostname") or c.get("name") or "Unknown" mac = c.get("mac", "Unknown") ip = c.get("ip", "N/A") is_wired = c.get("is_wired", False) conn_type = "Wired" if is_wired else "Wireless" essid = c.get("essid", "") tx_bytes = c.get("tx_bytes", 0) rx_bytes = c.get("rx_bytes", 0) lines.append(f"- {hostname}") lines.append(f" MAC: {mac}") lines.append(f" IP: {ip}") lines.append(f" Connection: {conn_type}") if essid: lines.append(f" SSID: {essid}") lines.append( f" Traffic: TX {format_bytes(tx_bytes)} / RX {format_bytes(rx_bytes)}" ) lines.append("") return "\n".join(lines)