hs_recent_contacts
Retrieve recently created HubSpot contacts, with optional filtering by lifecycle stage such as lead, marketingqualifiedlead, opportunity, or customer.
Instructions
Most recently created contacts, optionally filtered by lifecycle stage (lead, marketingqualifiedlead, opportunity, customer, etc.).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| lifecycleStage | No | Filter by lifecycle stage, e.g. 'lead', 'marketingqualifiedlead', 'opportunity', 'customer' |
Implementation Reference
- src/tools/contacts.ts:49-52 (schema)Zod schema for hs_recent_contacts input: optional limit (1-100, default 25) and optional lifecycleStage filter string.
export const RecentContactsSchema = z.object({ limit: z.number().int().min(1).max(100).default(25).optional(), lifecycleStage: z.string().optional().describe("Filter by lifecycle stage, e.g. 'lead', 'marketingqualifiedlead', 'opportunity', 'customer'"), }); - src/tools/contacts.ts:54-66 (handler)Handler function recentContacts that calls HubSpot POST /crm/v3/objects/contacts/search with descending createdate sort, optional lifecycle stage filter, and configurable limit.
export async function recentContacts(args: z.infer<typeof RecentContactsSchema>) { const body: Record<string, unknown> = { limit: args.limit ?? 25, properties: CONTACT_PROPS.split(","), sorts: [{ propertyName: "createdate", direction: "DESCENDING" }], }; if (args.lifecycleStage) { body.filterGroups = [{ filters: [{ propertyName: "lifecyclestage", operator: "EQ", value: args.lifecycleStage }], }]; } return hubspot("/crm/v3/objects/contacts/search", "POST", body); } - src/index.ts:103-108 (registration)Registration of the hs_recent_contacts tool on the MCP server using RecentContactsSchema.shape and the recentContacts handler.
server.tool( "hs_recent_contacts", "Most recently created contacts, optionally filtered by lifecycle stage (lead, marketingqualifiedlead, opportunity, customer, etc.).", RecentContactsSchema.shape, async (args) => { try { return ok(await recentContacts(args)); } catch (e) { return err(e); } }, ); - src/index.ts:11-14 (registration)Import of RecentContactsSchema and recentContacts from src/tools/contacts.ts into the main server file.
RecentContactsSchema, recentContacts, CreateContactSchema, createContact, UpdateContactSchema, updateContact, } from "./tools/contacts.js";