hs_list_lists
Retrieve all HubSpot contact lists, including static and active lists, with optional filtering by name substring to find specific lists quickly.
Instructions
List all HubSpot contact lists (static and active). Optionally filter by name substring.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | Filter by list name substring |
Implementation Reference
- src/tools/lists.ts:9-16 (handler)The actual handler function that executes the 'hs_list_lists' tool logic. It calls HubSpot GET /contacts/v1/lists with optional 'count' and 'query' parameters.
export async function listLists(args: z.infer<typeof ListListsSchema>) { const params: Record<string, string | number | boolean> = { count: args.limit ?? 50, offset: 0, }; if (args.query) params.query = args.query; return hubspot("/contacts/v1/lists", "GET", undefined, params); } - src/tools/lists.ts:4-7 (schema)Zod schema defining input validation for hs_list_lists: limit (number, 1-500, default 50, optional) and query (optional string for name filter).
export const ListListsSchema = z.object({ limit: z.number().int().min(1).max(500).default(50).optional(), query: z.string().optional().describe("Filter by list name substring"), }); - src/index.ts:195-200 (registration)Registration of the 'hs_list_lists' tool with the MCP server via server.tool(), binding the schema and handler.
server.tool( "hs_list_lists", "List all HubSpot contact lists (static and active). Optionally filter by name substring.", ListListsSchema.shape, async (args) => { try { return ok(await listLists(args)); } catch (e) { return err(e); } }, ); - src/index.ts:37-42 (registration)Import of ListListsSchema and listLists from src/tools/lists.ts into the main index file.
// Lists import { ListListsSchema, listLists, GetListSchema, getList, ListMembersSchema, listMembers, } from "./tools/lists.js"; - src/client.ts:16-48 (helper)The hubspot() helper function that executes the actual HTTP request to the HubSpot API, used by the listLists handler.
export async function hubspot<T = unknown>( path: string, method: "GET" | "POST" | "PATCH" | "DELETE" = "GET", body?: unknown, params?: Record<string, string | number | boolean>, ): Promise<T> { const token = getToken(); let url = `${BASE_URL}${path}`; if (params && method === "GET") { const qs = new URLSearchParams( Object.entries(params).map(([k, v]) => [k, String(v)]), ).toString(); if (qs) url += `?${qs}`; } const res = await fetch(url, { method, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", }, ...(body && method !== "GET" ? { body: JSON.stringify(body) } : {}), }); if (!res.ok) { const text = await res.text().catch(() => res.statusText); throw new HubSpotError(`HubSpot API error (${res.status}): ${text}`, res.status); } if (res.status === 204) return undefined as T; return (await res.json()) as T; }