HubSpot MCP Server

Instructions

🛡️ Guardrails:
  1.  Data Modification Warning: This tool modifies HubSpot data. Only use when the user has explicitly requested to update their CRM.

🎯 Purpose:
  1. Establishes relationships between HubSpot objects, linking records across different object types, by creating associations between objects in batch.
  2. Uses a single set of association types for all associations in the batch.

📋 Prerequisites:
  1. Use the hubspot-get-user-details tool to get the OwnerId and UserId if you don't have that already.
  2. Use the hubspot-get-association-definitions tool to identify valid association types before creating associations.

Implementation Reference

• dist/tools/associations/batchCreateAssociationsTool.js:60-90 (handler)

  Implements the tool logic: maps types to each input, calls HubSpot CRM v4 associations batch create API endpoint, returns formatted response or error.

  async process(args) {
      try {
          // Add types to each input
          const inputs = args.inputs.map(input => ({
              ...input,
              types: args.types,
          }));
          const response = await this.client.post(`/crm/v4/associations/${args.fromObjectType}/${args.toObjectType}/batch/create`, {
              body: { inputs },
          });
          return {
              content: [
                  {
                      type: 'text',
                      text: JSON.stringify(response, null, 2),
                  },
              ],
          };
      }
      catch (error) {
          return {
              content: [
                  {
                      type: 'text',
                      text: `Error creating HubSpot associations: ${error instanceof Error ? error.message : String(error)}`,
                  },
              ],
              isError: true,
          };
      }
  }

• dist/tools/associations/batchCreateAssociationsTool.js:6-29 (schema)

  Zod schemas for association types, inputs, and the main ObjectAssociationSchema defining the tool's input structure including object types, association types, and batch inputs.

  const AssociationTypeSchema = z.object({
      associationCategory: z.enum(['HUBSPOT_DEFINED', 'USER_DEFINED', 'INTEGRATOR_DEFINED']),
      associationTypeId: z.number().int().positive(),
  });
  const AssociationInputSchema = z.object({
      from: z.object({
          id: z.string().describe('The ID of the object to create association from'),
      }),
      to: z.object({
          id: z.string().describe('The ID of the object to create association to'),
      }),
  });
  const ObjectAssociationSchema = z.object({
      fromObjectType: z
          .string()
          .describe(`The type of HubSpot object to create association from. Valid values include: ${HUBSPOT_OBJECT_TYPES.join(', ')}. For custom objects, use the hubspot-get-schemas tool to get the objectType.`),
      toObjectType: z
          .string()
          .describe(`The type of HubSpot object to create association to. Valid values include: ${HUBSPOT_OBJECT_TYPES.join(', ')}. For custom objects, use the hubspot-get-schemas tool to get the objectType.`),
      types: z.array(AssociationTypeSchema).min(1).describe('The types of associations to create'),
      inputs: z
          .array(AssociationInputSchema)
          .min(1)
          .describe('List of association inputs defining the relationships to create. (max 100 associations per batch)'),

• dist/tools/associations/batchCreateAssociationsTool.js:31-53 (registration)

  ToolDefinition object containing the tool name 'hubspot-batch-create-associations', detailed description, JSON schema from Zod, and annotations; passed to BaseTool constructor.

  const ToolDefinition = {
      name: 'hubspot-batch-create-associations',
      description: `
      🛡️ Guardrails:
        1.  Data Modification Warning: This tool modifies HubSpot data. Only use when the user has explicitly requested to update their CRM.
  
      🎯 Purpose:
        1. Establishes relationships between HubSpot objects, linking records across different object types, by creating associations between objects in batch.
        2. Uses a single set of association types for all associations in the batch.
  
      📋 Prerequisites:
        1. Use the hubspot-get-user-details tool to get the OwnerId and UserId if you don't have that already.
        2. Use the hubspot-get-association-definitions tool to identify valid association types before creating associations.
    `,
      inputSchema: zodToJsonSchema(ObjectAssociationSchema),
      annotations: {
          title: 'Create CRM Object Associations in Batch',
          readOnlyHint: false,
          destructiveHint: false,
          idempotentHint: true,
          openWorldHint: true,
      },
  };

• dist/tools/toolsRegistry.js:30-30 (registration)

  Instantiates the BatchCreateAssociationsTool and registers it with the central tools registry.

  registerTool(new BatchCreateAssociationsTool());