HubSpot MCP Server

Instructions

Implementation Reference

• src/hubspot-client.ts:316-389 (handler)

  Core handler function that implements the hubspot_create_contact tool logic: searches for existing contact to avoid duplicates, then creates a new contact via HubSpot CRM API with provided properties.
  async createContact( firstname: string, lastname: string, email?: string, properties?: Record<string, any> ): Promise<any> { try { // Search for existing contacts with same name and company const company = properties?.company; // Use type assertion to satisfy the HubSpot API client types const searchRequest = { filterGroups: [{ filters: [ { propertyName: 'firstname', operator: 'EQ', value: firstname } as any, { propertyName: 'lastname', operator: 'EQ', value: lastname } as any ] }] } as any; // Add company filter if provided if (company) { searchRequest.filterGroups[0].filters.push({ propertyName: 'company', operator: 'EQ', value: company } as any); } const searchResponse = await this.client.crm.contacts.searchApi.doSearch(searchRequest); if (searchResponse.total > 0) { // Contact already exists return { message: 'Contact already exists', contact: searchResponse.results[0] }; } // If no existing contact found, proceed with creation const contactProperties: Record<string, any> = { firstname, lastname }; // Add email if provided if (email) { contactProperties.email = email; } // Add any additional properties if (properties) { Object.assign(contactProperties, properties); } // Create contact const apiResponse = await this.client.crm.contacts.basicApi.create({ properties: contactProperties }); return apiResponse; } catch (error: any) { console.error('Error creating contact:', error); throw new Error(`HubSpot API error: ${error.message}`); } }
• src/index.ts:234-247 (handler)

  MCP server handler for the tool: receives arguments from MCP CallToolRequest, invokes HubSpotClient.createContact, and returns JSON-formatted result.
  case 'hubspot_create_contact': { const result = await this.hubspot.createContact( args.firstname as string, args.lastname as string, args.email as string | undefined, args.properties as Record<string, any> | undefined ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }; }
• src/index.ts:79-104 (schema)

  Tool schema definition including input schema with required firstname/lastname and optional email/properties, registered in MCP ListTools response.
  { name: 'hubspot_create_contact', description: 'Create a new contact in HubSpot', inputSchema: { type: 'object', properties: { firstname: { type: 'string', description: "Contact's first name" }, lastname: { type: 'string', description: "Contact's last name" }, email: { type: 'string', description: "Contact's email address" }, properties: { type: 'object', description: 'Additional contact properties', additionalProperties: true } }, required: ['firstname', 'lastname'] }
• src/index.ts:76-227 (registration)

  Registration of the tool in MCP server's ListToolsRequest handler, including the full tool definition.
  this.server.setRequestHandler(ListToolsRequestSchema, async () => { // Define available tools const tools: Tool[] = [ { name: 'hubspot_create_contact', description: 'Create a new contact in HubSpot', inputSchema: { type: 'object', properties: { firstname: { type: 'string', description: "Contact's first name" }, lastname: { type: 'string', description: "Contact's last name" }, email: { type: 'string', description: "Contact's email address" }, properties: { type: 'object', description: 'Additional contact properties', additionalProperties: true } }, required: ['firstname', 'lastname'] } }, { name: 'hubspot_create_company', description: 'Create a new company in HubSpot', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Company name' }, properties: { type: 'object', description: 'Additional company properties', additionalProperties: true } }, required: ['name'] } }, { name: 'hubspot_get_company_activity', description: 'Get activity history for a specific company', inputSchema: { type: 'object', properties: { company_id: { type: 'string', description: 'HubSpot company ID' } }, required: ['company_id'] } }, { name: 'hubspot_get_recent_engagements', description: 'Get recent engagement activities across all contacts and companies', inputSchema: { type: 'object', properties: { days: { type: 'number', description: 'Number of days to look back (default: 7)', default: 7 }, limit: { type: 'number', description: 'Maximum number of engagements to return (default: 50)', default: 50 } } } }, { name: 'hubspot_get_active_companies', description: 'Get most recently active companies from HubSpot', inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'Maximum number of companies to return (default: 10)', default: 10 } } } }, { name: 'hubspot_get_active_contacts', description: 'Get most recently active contacts from HubSpot', inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'Maximum number of contacts to return (default: 10)', default: 10 } } } }, { name: 'hubspot_update_contact', description: 'Update an existing contact in HubSpot (ignores if contact does not exist)', inputSchema: { type: 'object', properties: { contact_id: { type: 'string', description: 'HubSpot contact ID to update' }, properties: { type: 'object', description: 'Contact properties to update', additionalProperties: true } }, required: ['contact_id', 'properties'] } }, { name: 'hubspot_update_company', description: 'Update an existing company in HubSpot (ignores if company does not exist)', inputSchema: { type: 'object', properties: { company_id: { type: 'string', description: 'HubSpot company ID to update' }, properties: { type: 'object', description: 'Company properties to update', additionalProperties: true } }, required: ['company_id', 'properties'] } } ]; return { tools }; });