get_clients
Retrieve all currently connected clients on a UniFi network to monitor active devices and manage network access. Optionally include historical client data for comprehensive network 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)MCP tool handler for 'get_clients': extracts parameters, calls UniFiClient.get_clients() or get_all_clients(), formats output with format_clients, returns 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 and description for the 'get_clients' tool, defined in list_tools(). Supports optional 'include_offline' boolean parameter.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:45-59 (registration)Registration of 'get_clients' tool in @server.list_tools(), providing name, description, and schema.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": [], }, ),
- Core UniFiClient method that fetches currently connected clients via API endpoint '/api/s/{site}/stat/sta'.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-303 (helper)Helper function to format the list of clients into a human-readable multi-line string.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)