UniFi MCP Server

Implementation Reference

• src/tools/network.js:23-28 (handler)

  MCP tool handler for 'get_system_status' which fetches the system status using the unifi client and returns it as formatted JSON in text content.

  handler: async () => {
    const status = await unifi.getSystemStatus();
    return {
      content: [{ type: 'text', text: JSON.stringify(status, null, 2) }]
    };
  }

• src/tools/network.js:22-22 (schema)

  Input schema for the 'get_system_status' tool, accepting no parameters.

  schema: z.object({}),

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

  Registers the networkTools module containing the 'get_system_status' tool to the MCP server.

  registerToolsFromModule(networkTools);

• src/unifi-client.js:313-394 (helper)

  Helper function getSystemStatus() that implements the core logic: aggregates comprehensive status data (hosts, sites, devices, clients) from UniFi Cloud API endpoints.

  export async function getSystemStatus() {
    const status = {
      timestamp: new Date().toISOString(),
      hosts: [],
      summary: {
        totalHosts: 0,
        totalSites: 0,
        totalDevices: 0,
        totalClients: 0,
        onlineDevices: 0,
        offlineDevices: 0
      }
    };
  
    try {
      const hostsResponse = await listHosts();
      const hosts = hostsResponse.data || [];
      status.summary.totalHosts = hosts.length;
  
      for (const host of hosts) {
        const hostStatus = {
          id: host.id,
          name: host.name || host.hostname,
          type: host.type,
          status: host.status,
          sites: [],
          deviceCount: 0,
          clientCount: 0
        };
  
        try {
          const sitesResponse = await getSitesForHost(host.id);
          const sites = sitesResponse.data || [];
          status.summary.totalSites += sites.length;
  
          for (const site of sites) {
            hostStatus.sites.push({
              id: site.id,
              name: site.name
            });
          }
        } catch (e) {
          // Site fetch may fail for some hosts
        }
  
        try {
          const devicesResponse = await getDevicesForHost(host.id);
          const devices = devicesResponse.data || [];
          hostStatus.deviceCount = devices.length;
          status.summary.totalDevices += devices.length;
  
          for (const device of devices) {
            if (device.state === 'ONLINE' || device.state === 1) {
              status.summary.onlineDevices++;
            } else {
              status.summary.offlineDevices++;
            }
          }
        } catch (e) {
          // Device fetch may fail
        }
  
        try {
          const clientsResponse = await getClientsForHost(host.id);
          const clients = clientsResponse.data || [];
          hostStatus.clientCount = clients.length;
          status.summary.totalClients += clients.length;
        } catch (e) {
          // Client fetch may fail
        }
  
        status.hosts.push(hostStatus);
      }
  
      status.ok = true;
    } catch (error) {
      status.ok = false;
      status.error = error.message;
    }
  
    return status;
  }