UniFi MCP Server

Implementation Reference

• src/tools/clients.js:117-137 (handler)

  The core handler function implementing the 'find_client_by_mac' tool. It normalizes the MAC address, fetches all clients via unifi.listAllClients(), filters for exact or partial MAC matches, and returns a structured JSON response with match details.

  handler: async ({ mac }) => {
    const normalizedMac = mac.toLowerCase().replace(/[:-]/g, '');
    const allClients = await unifi.listAllClients();
    const clients = allClients.data || [];
  
    const matches = clients.filter(c => {
      const clientMac = (c.mac || '').toLowerCase().replace(/[:-]/g, '');
      return clientMac === normalizedMac || clientMac.includes(normalizedMac);
    });
  
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          searchMac: mac,
          matchCount: matches.length,
          matches
        }, null, 2)
      }]
    };
  }

• src/tools/clients.js:114-116 (schema)

  Zod schema defining the input parameters for the tool: a required 'mac' string.

  schema: z.object({
    mac: z.string().describe('The MAC address to search for')
  }),

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

  Line registering the clientTools module (which includes find_client_by_mac) with the MCP server via the registerToolsFromModule utility.

  registerToolsFromModule(clientTools);

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

  Helper function called by the tool handler to retrieve all clients across hosts/sites. (Note: full implementation not read, but key dependency.)

  export async function listAllClients() {