HubSpot MCP Server

Instructions

🎯 Purpose:
  1. This tool retrieves a complete catalog of properties for any HubSpot object type.

🧭 Usage Guidance:
  1. This API has a large response that can consume a lot of tokens. Use the hubspot-list-objects tool to sample existing objects for the object type first.
  2. Try to use the hubspot-get-property tool to get a specific property.
  3. Use at the beginning of workflows to understand available data structures.

Implementation Reference

• dist/tools/properties/listPropertiesTool.js:45-82 (handler)

  The process method implements the core logic: constructs query params for archived and includeHidden, calls HubSpot API /crm/v3/properties/{objectType}, filters results to key fields (name, label, type, description, groupName), returns formatted JSON or error response.

  async process(args) {
      try {
          const queryParams = new URLSearchParams();
          queryParams.append('archived', args.archived?.toString() || 'false');
          queryParams.append('includeHidden', args.includeHidden?.toString() || 'false');
          const response = await this.client.get(`/crm/v3/properties/${args.objectType}?${queryParams.toString()}`);
          // Filter each result to only include the specified fields
          const filteredResults = response.results.map((property) => ({
              name: property.name,
              label: property.label,
              type: property.type,
              description: property.description,
              groupName: property.groupName,
          }));
          return {
              content: [
                  {
                      type: 'text',
                      text: JSON.stringify({
                          results: filteredResults,
                          paging: response.paging,
                      }, null, 2),
                  },
              ],
          };
      }
      catch (error) {
          return {
              content: [
                  {
                      type: 'text',
                      text: `Error listing HubSpot properties for ${args.objectType}: ${error instanceof Error ? error.message : String(error)}`,
                  },
              ],
              isError: true,
          };
      }
  }

• dist/tools/properties/listPropertiesTool.js:6-18 (schema)

  Input schema using Zod: requires objectType string, optional archived and includeHidden booleans with defaults to false.

  const PropertiesListSchema = z.object({
      objectType: z
          .string()
          .describe(`The type of HubSpot object to get properties for. Valid values include: ${HUBSPOT_OBJECT_TYPES.join(', ')}. For custom objects, use the hubspot-get-schemas tool to get the objectType.`),
      archived: z
          .boolean()
          .default(false)
          .describe('Whether to return only properties that have been archived.'),
      includeHidden: z
          .boolean()
          .default(false)
          .describe('Whether to include hidden properties in the response.'),
  });

• dist/tools/properties/listPropertiesTool.js:19-38 (registration)

  ToolDefinition object specifying the tool name, description, converted input schema, and annotations like readOnlyHint.

  const ToolDefinition = {
      name: 'hubspot-list-properties',
      description: `
      🎯 Purpose:
        1. This tool retrieves a complete catalog of properties for any HubSpot object type.
  
      🧭 Usage Guidance:
        1. This API has a large response that can consume a lot of tokens. Use the hubspot-list-objects tool to sample existing objects for the object type first.
        2. Try to use the hubspot-get-property tool to get a specific property.
        3. Use at the beginning of workflows to understand available data structures.
    `,
      inputSchema: zodToJsonSchema(PropertiesListSchema),
      annotations: {
          title: 'List CRM Properties',
          readOnlyHint: true,
          destructiveHint: false,
          idempotentHint: true,
          openWorldHint: true,
      },
  };

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

  Instantiates and registers the PropertiesListTool with the tools registry.

  registerTool(new PropertiesListTool());

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

  Imports the PropertiesListTool class from its implementation file.

  import { PropertiesListTool } from './properties/listPropertiesTool.js';