UniFi MCP Server

Implementation Reference

• src/tools/clients.js:173-240 (handler)

  The main handler function that implements the tool logic: fetches client list, computes aggregate bandwidth stats (total RX/TX, by wired/wireless, top 10 users), formats bytes, and returns JSON summary.

  handler: async ({ hostId }) => {
    let clients;
    if (hostId) {
      const response = await unifi.getClientsForHost(hostId);
      clients = response.data || [];
    } else {
      const response = await unifi.listAllClients();
      clients = response.data || [];
    }
  
    // Calculate bandwidth stats
    const summary = {
      totalClients: clients.length,
      totalRxBytes: 0,
      totalTxBytes: 0,
      byConnectionType: {
        wired: { count: 0, rxBytes: 0, txBytes: 0 },
        wireless: { count: 0, rxBytes: 0, txBytes: 0 }
      },
      topByUsage: []
    };
  
    const clientsWithUsage = clients.map(c => {
      const rx = c.rxBytes || c.rx_bytes || 0;
      const tx = c.txBytes || c.tx_bytes || 0;
      summary.totalRxBytes += rx;
      summary.totalTxBytes += tx;
  
      const isWired = c.isWired || c.is_wired;
      if (isWired) {
        summary.byConnectionType.wired.count++;
        summary.byConnectionType.wired.rxBytes += rx;
        summary.byConnectionType.wired.txBytes += tx;
      } else {
        summary.byConnectionType.wireless.count++;
        summary.byConnectionType.wireless.rxBytes += rx;
        summary.byConnectionType.wireless.txBytes += tx;
      }
  
      return {
        name: c.name || c.hostname || c.mac,
        mac: c.mac,
        totalUsage: rx + tx,
        rxBytes: rx,
        txBytes: tx
      };
    });
  
    // Sort by usage and get top 10
    summary.topByUsage = clientsWithUsage
      .sort((a, b) => b.totalUsage - a.totalUsage)
      .slice(0, 10);
  
    // Format bytes
    const formatBytes = (bytes) => {
      if (bytes < 1024) return `${bytes} B`;
      if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} KB`;
      if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(2)} MB`;
      return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`;
    };
  
    summary.totalRxFormatted = formatBytes(summary.totalRxBytes);
    summary.totalTxFormatted = formatBytes(summary.totalTxBytes);
  
    return {
      content: [{ type: 'text', text: JSON.stringify(summary, null, 2) }]
    };
  }

• src/tools/clients.js:170-172 (schema)

  Zod schema defining the optional 'hostId' input parameter for filtering clients by host.

  schema: z.object({
    hostId: z.string().optional().describe('Optional: Filter by host ID')
  }),

• src/server.js:30-30 (registration)

  Registers the entire clientTools module (including get_client_bandwidth_summary) with the MCP server using the dynamic registration function.

  registerToolsFromModule(clientTools);

• src/server.js:16-25 (registration)

  Helper function that iterates over a tools module and registers each tool individually on the MCP server.

  const registerToolsFromModule = (toolsModule) => {
    Object.entries(toolsModule).forEach(([name, toolConfig]) => {
      server.tool(
        name,
        toolConfig.schema,
        toolConfig.handler,
        { description: toolConfig.description }
      );
    });
  };