UniFi MCP Server

Implementation Reference

• src/tools/clients.js:59-75 (handler)

  MCP tool handler for 'block_client'. Validates confirmation and invokes the underlying unifi.blockClient function.

  handler: async ({ hostId, siteId, mac, confirm }) => {
    if (!confirm) {
      return {
        content: [{
          type: 'text',
          text: 'Client block cancelled. Set confirm=true to proceed. Note: You can unblock the client later using unblock_client.'
        }]
      };
    }
    const result = await unifi.blockClient(hostId, siteId, mac);
    return {
      content: [{
        type: 'text',
        text: `Client ${mac} has been blocked. Use unblock_client to reverse this action. ${JSON.stringify(result, null, 2)}`
      }]
    };
  }

• src/tools/clients.js:53-58 (schema)

  Zod input schema defining parameters: hostId, siteId, mac, confirm.

  schema: z.object({
    hostId: z.string().describe('The host ID'),
    siteId: z.string().describe('The site ID'),
    mac: z.string().describe('The client MAC address'),
    confirm: z.boolean().describe('Confirm you want to block this client')
  }),

• src/tools/clients.js:51-76 (registration)

  Tool definition and registration object for 'block_client' within clientTools module.

  block_client: {
    description: 'Block a client from the network. The client will be disconnected and prevented from reconnecting.',
    schema: z.object({
      hostId: z.string().describe('The host ID'),
      siteId: z.string().describe('The site ID'),
      mac: z.string().describe('The client MAC address'),
      confirm: z.boolean().describe('Confirm you want to block this client')
    }),
    handler: async ({ hostId, siteId, mac, confirm }) => {
      if (!confirm) {
        return {
          content: [{
            type: 'text',
            text: 'Client block cancelled. Set confirm=true to proceed. Note: You can unblock the client later using unblock_client.'
          }]
        };
      }
      const result = await unifi.blockClient(hostId, siteId, mac);
      return {
        content: [{
          type: 'text',
          text: `Client ${mac} has been blocked. Use unblock_client to reverse this action. ${JSON.stringify(result, null, 2)}`
        }]
      };
    }
  },

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

  Registers all tools from clientTools (including block_client) to the MCP server.

  registerToolsFromModule(clientTools);

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

  Underlying helper function that performs the UniFi Cloud API POST request to block the client.

  export async function blockClient(hostId, siteId, mac) {
    const response = await cloudApi.post(`/v1/hosts/${hostId}/sites/${siteId}/clients/${mac}/block`);
    return response.data;
  }