List Groups
list_groupsList WhatsApp groups from a pinned instance. Filter by case-insensitive subject search and set a limit to control payload size.
Instructions
List WhatsApp groups for the pinned instance. Supports search and limit to prevent large payloads.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | Case-insensitive substring match against group subject. Omit for no filter. | |
| limit | No | Max results to return (default 50, max 500). |
Implementation Reference
- src/tools/list-groups.ts:28-71 (handler)Registers the 'list_groups' tool handler: calls Evolution API to fetch all groups, optionally filters by subject (case-insensitive), sorts alphabetically, limits results, and normalizes output.
export function registerListGroups(server: McpServer, client: EvolutionClient): void { server.registerTool( "list_groups", { title: "List Groups", description: "List WhatsApp groups for the pinned instance. Supports search and limit to prevent large payloads.", inputSchema: schema, }, async (args) => { try { const data = await client.get<GroupItem[]>( `/group/fetchAllGroups/${client.instanceName}?getParticipants=false` ); let groups = Array.isArray(data) ? data : []; // Client-side search filter (Evolution API has no query filter) if (args.search) { const needle = args.search.toLowerCase(); groups = groups.filter((g) => g.subject?.toLowerCase().includes(needle)); } // Sort by subject asc for stable results groups.sort((a, b) => (a.subject ?? "").localeCompare(b.subject ?? "")); // Cap results const limit = args.limit ?? 50; groups = groups.slice(0, limit); // Normalize to compact shape — drop owner to shrink payload const normalized = groups.map(({ id, subject, size }) => ({ id, subject, size })); return { content: [{ type: "text" as const, text: JSON.stringify(normalized, null, 2) }], }; } catch (e) { if (e instanceof McpError) { return { isError: true, content: [{ type: "text" as const, text: e.message }] }; } throw e; } } ); } - src/tools/list-groups.ts:13-26 (schema)Zod schema defining optional 'search' (string) and optional 'limit' (int 1-500, default 50) input parameters.
const schema = { search: z .string() .optional() .describe("Case-insensitive substring match against group subject. Omit for no filter."), limit: z .number() .int() .min(1) .max(500) .default(50) .optional() .describe("Max results to return (default 50, max 500)."), }; - src/tools/list-groups.ts:6-11 (helper)TypeScript interface for raw group items returned by the Evolution API.
interface GroupItem { id: string; subject: string; size?: number; owner?: string; } - src/tools/index.ts:78-78 (registration)Calls registerListGroups inside registerAllTools, wiring the tool into the MCP server.
registerListGroups(server, client);