hs_list_company_contacts
Retrieve all contacts belonging to a specific company in HubSpot. Input the company ID and optionally limit results up to 100. Ideal for viewing or exporting company-contact relationships.
Instructions
List all contacts associated with a company.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| companyId | Yes | HubSpot company ID | |
| limit | No |
Implementation Reference
- src/tools/companies.ts:40-53 (handler)The main handler function that executes the tool logic. It fetches associated contact IDs for a company and then retrieves full contact details in a batch read.
export async function listCompanyContacts(args: z.infer<typeof ListCompanyContactsSchema>) { const assoc = await hubspot<{ results: Array<{ id: string }> }>( `/crm/v3/objects/companies/${args.companyId}/associations/contacts`, "GET", undefined, { limit: args.limit ?? 20 }, ); const ids = assoc.results.map((r) => r.id); if (!ids.length) return { results: [] }; return hubspot("/crm/v3/objects/contacts/batch/read", "POST", { inputs: ids.map((id) => ({ id })), properties: ["firstname", "lastname", "email", "jobtitle", "phone", "lifecyclestage"], }); } - src/tools/companies.ts:35-38 (schema)Zod schema defining the input validation for the tool: companyId (string) and optional limit (1-100, default 20).
export const ListCompanyContactsSchema = z.object({ companyId: z.string().describe("HubSpot company ID"), limit: z.number().int().min(1).max(100).default(20).optional(), }); - src/index.ts:140-145 (registration)Registration of the tool on the MCP server with name 'hs_list_company_contacts', description, schema, and handler binding.
server.tool( "hs_list_company_contacts", "List all contacts associated with a company.", ListCompanyContactsSchema.shape, async (args) => { try { return ok(await listCompanyContacts(args)); } catch (e) { return err(e); } }, ); - src/index.ts:20-21 (registration)Import statement that brings in the schema and handler from the companies module.
ListCompanyContactsSchema, listCompanyContacts, } from "./tools/companies.js";