HubSpot MCP Server

Instructions

Implementation Reference

• src/hubspot-client.ts:86-200 (handler)

  Core handler function implementing the hubspot_get_company_activity tool logic: fetches engagements associated with a company using HubSpot CRM Associations API, retrieves details for each engagement, formats them by type (NOTE, EMAIL, TASK, MEETING, CALL), and converts datetime fields.
  async getCompanyActivity(companyId: string): Promise<any> { try { // Step 1: Get all engagement IDs associated with the company using CRM Associations v4 API const associatedEngagements = await this.client.crm.associations.v4.basicApi.getPage( 'companies', companyId, 'engagements', undefined, 500 ); // Extract engagement IDs from the associations response const engagementIds: string[] = []; if (associatedEngagements.results) { for (const result of associatedEngagements.results) { engagementIds.push(result.toObjectId); } } // Step 2: Get detailed information for each engagement const activities = []; for (const engagementId of engagementIds) { const engagementResponse = await this.client.apiRequest({ method: 'GET', path: `/engagements/v1/engagements/${engagementId}` }); // Ensure we have a proper response body const responseBody = engagementResponse.body as any; const engagementData = responseBody.engagement || {}; const metadata = responseBody.metadata || {}; // Format the engagement const formattedEngagement: Record<string, any> = { id: engagementData.id, type: engagementData.type, created_at: engagementData.createdAt, last_updated: engagementData.lastUpdated, created_by: engagementData.createdBy, modified_by: engagementData.modifiedBy, timestamp: engagementData.timestamp, associations: (engagementResponse.body as any).associations || {} }; // Add type-specific metadata formatting if (engagementData.type === 'NOTE') { formattedEngagement.content = metadata.body || ''; } else if (engagementData.type === 'EMAIL') { formattedEngagement.content = { subject: metadata.subject || '', from: { raw: metadata.from?.raw || '', email: metadata.from?.email || '', firstName: metadata.from?.firstName || '', lastName: metadata.from?.lastName || '' }, to: (metadata.to || []).map((recipient: any) => ({ raw: recipient.raw || '', email: recipient.email || '', firstName: recipient.firstName || '', lastName: recipient.lastName || '' })), cc: (metadata.cc || []).map((recipient: any) => ({ raw: recipient.raw || '', email: recipient.email || '', firstName: recipient.firstName || '', lastName: recipient.lastName || '' })), bcc: (metadata.bcc || []).map((recipient: any) => ({ raw: recipient.raw || '', email: recipient.email || '', firstName: recipient.firstName || '', lastName: recipient.lastName || '' })), sender: { email: metadata.sender?.email || '' }, body: metadata.text || metadata.html || '' }; } else if (engagementData.type === 'TASK') { formattedEngagement.content = { subject: metadata.subject || '', body: metadata.body || '', status: metadata.status || '', for_object_type: metadata.forObjectType || '' }; } else if (engagementData.type === 'MEETING') { formattedEngagement.content = { title: metadata.title || '', body: metadata.body || '', start_time: metadata.startTime, end_time: metadata.endTime, internal_notes: metadata.internalMeetingNotes || '' }; } else if (engagementData.type === 'CALL') { formattedEngagement.content = { body: metadata.body || '', from_number: metadata.fromNumber || '', to_number: metadata.toNumber || '', duration_ms: metadata.durationMilliseconds, status: metadata.status || '', disposition: metadata.disposition || '' }; } activities.push(formattedEngagement); } // Convert any datetime fields and return return convertDatetimeFields(activities); } catch (error: any) { console.error('Error getting company activity:', error); return { error: error.message }; } }
• src/index.ts:125-138 (registration)

  Tool registration in the ListToolsRequestSchema handler, defining the tool name, description, and input schema requiring 'company_id'.
  { 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'] } },
• src/index.ts:262-270 (handler)

  MCP server tool handler switch case that receives tool call arguments, invokes HubSpotClient.getCompanyActivity, and returns the JSON-formatted result as MCP content.
  case 'hubspot_get_company_activity': { const result = await this.hubspot.getCompanyActivity(args.company_id as string); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }; }
• src/hubspot-client.ts:7-29 (helper)

  Helper utility function used by getCompanyActivity to recursively convert Date objects and nested structures to ISO strings for JSON serialization.
  export function convertDatetimeFields(obj: any): any { if (obj === null || obj === undefined) { return obj; } if (typeof obj === 'object') { if (obj instanceof Date) { return obj.toISOString(); } if (Array.isArray(obj)) { return obj.map(item => convertDatetimeFields(item)); } const result: Record<string, any> = {}; for (const [key, value] of Object.entries(obj)) { result[key] = convertDatetimeFields(value); } return result; } return obj; }