disconnect_client

Force disconnect a client from a UniFi network by MAC address to manage network access and resolve connectivity issues.

Instructions

Force disconnect a client from the network

Input Schema

TableJSON Schema

Name	Required	Description	Default
`mac`	Yes	MAC address of the client to disconnect

Implementation Reference

src/unifi_mcp/server.py:206-214 (handler)

MCP tool handler for disconnect_client: extracts MAC from arguments, calls UniFiClient.disconnect_client(mac), and returns success message.

case "disconnect_client":
    mac = arguments.get("mac", "")
    await client.disconnect_client(mac)
    return [
        TextContent(
            type="text",
            text=f"Client {mac} has been disconnected.",
        )
    ]

src/unifi_mcp/server.py:88-101 (schema)

Input schema definition for the disconnect_client tool, requiring a 'mac' string parameter.

Tool(
    name="disconnect_client",
    description="Force disconnect a client from the network",
    inputSchema={
        "type": "object",
        "properties": {
            "mac": {
                "type": "string",
                "description": "MAC address of the client to disconnect",
            }
        },
        "required": ["mac"],
    },
),

src/unifi_mcp/server.py:16-146 (registration)

Registers the disconnect_client tool via @server.list_tools() decorator by including it in the returned list of available tools.

@server.list_tools()
async def list_tools() -> list[Tool]:
    """List all available UniFi MCP tools."""
    return [
        # Device tools
        Tool(
            name="get_devices",
            description="Get all UniFi network devices (access points, switches, gateways)",
            inputSchema={
                "type": "object",
                "properties": {},
                "required": [],
            },
        ),
        Tool(
            name="restart_device",
            description="Restart a UniFi network device by its MAC address",
            inputSchema={
                "type": "object",
                "properties": {
                    "mac": {
                        "type": "string",
                        "description": "MAC address of the device to restart (e.g., '00:11:22:33:44:55')",
                    }
                },
                "required": ["mac"],
            },
        ),
        # Client 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": [],
            },
        ),
        Tool(
            name="block_client",
            description="Block a client from accessing the network",
            inputSchema={
                "type": "object",
                "properties": {
                    "mac": {
                        "type": "string",
                        "description": "MAC address of the client to block",
                    }
                },
                "required": ["mac"],
            },
        ),
        Tool(
            name="unblock_client",
            description="Unblock a previously blocked client",
            inputSchema={
                "type": "object",
                "properties": {
                    "mac": {
                        "type": "string",
                        "description": "MAC address of the client to unblock",
                    }
                },
                "required": ["mac"],
            },
        ),
        Tool(
            name="disconnect_client",
            description="Force disconnect a client from the network",
            inputSchema={
                "type": "object",
                "properties": {
                    "mac": {
                        "type": "string",
                        "description": "MAC address of the client to disconnect",
                    }
                },
                "required": ["mac"],
            },
        ),
        # Site tools
        Tool(
            name="get_sites",
            description="Get all UniFi sites configured on the controller",
            inputSchema={
                "type": "object",
                "properties": {},
                "required": [],
            },
        ),
        Tool(
            name="get_site_health",
            description="Get health status for the current site",
            inputSchema={
                "type": "object",
                "properties": {},
                "required": [],
            },
        ),
        Tool(
            name="get_networks",
            description="Get all network configurations for the current site",
            inputSchema={
                "type": "object",
                "properties": {},
                "required": [],
            },
        ),
        # Activity tools
        Tool(
            name="get_device_activity",
            description="Get activity for a specific device including connected clients and their traffic",
            inputSchema={
                "type": "object",
                "properties": {
                    "mac": {
                        "type": "string",
                        "description": "MAC address of the device (AP or switch)",
                    }
                },
                "required": ["mac"],
            },
        ),
    ]

src/unifi_mcp/unifi_client.py:266-280 (helper)

Low-level implementation that sends UniFi API request to kick (disconnect) the client by MAC address.

async def disconnect_client(self, mac: str) -> bool:
    """Force disconnect a client.

    Args:
        mac: Client MAC address.

    Returns:
        True if disconnect command was sent successfully.
    """
    await self._request(
        "POST",
        "/api/s/{site}/cmd/stamgr",
        json={"cmd": "kick-sta", "mac": mac.lower()},
    )
    return True

UniFi MCP Server