HubSpot MCP Server

🎯 Purpose 1. Authenticates and analyzes the current HubSpot access token, providing context about the user's permissions and account details. 🧭 Usage Guidance: 1. This tool must be used before performing any operations with Hubspot tools to determine the identity of the user, and permissions they have on their Hubspot account. 📦 Returns: 1. User ID, Hub ID, App ID, token type, a comprehensive list of authorized API scopes, and detailed owner information, and account information. 2. The uiDomain and hubId can be used to construct URLs to the HubSpot UI for the user. 3. If the user is an owner, the ownerId will help identify objects that are owned by the user.

🎯 Purpose: 1. Retrieves a paginated list of objects of a specified type from HubSpot. 📦 Returns: 1. Collection of objects with their properties and metadata, plus pagination information. 🧭 Usage Guidance: 1. Use for initial data exploration to understand the data structure of a HubSpot object type. 2. Helps list objects when the search criteria or filter criteria is not clear. 3. Use hubspot-search-objects for targeted queries when the data structure is known. 4. Use hubspot-batch-read-objects to retrieve specific objects by their IDs. 5. Use hubspot-list-associations to list associations between objects.

🎯 Purpose: 1. Performs advanced filtered searches across HubSpot object types using complex criteria. 📋 Prerequisites: 1. Use the hubspot-list-objects tool to sample existing objects for the object type. 2. If hubspot-list-objects tool's response isn't helpful, use hubspot-list-properties tool. 📦 Returns: 1. Filtered collection matching specific criteria with pagination information. 🧭 Usage Guidance: 1. Preferred for targeted data retrieval when exact filtering criteria are known. Supports complex boolean logic through filter groups. 2. Use hubspot-list-objects when filter criteria is not specified or clear or when a search fails. 3. Use hubspot-batch-read-objects to retrieve specific objects by their IDs. 4. Use hubspot-list-associations to get the associations between objects. 🔍 Filtering Capabilities: 1. Think of "filterGroups" as separate search conditions that you want to combine with OR logic (meaning ANY of them can match). 2. If you want to find things that match ALL of several conditions (AND logic), put those conditions together in the same filters list. 3. If you want to find things that match AT LEAST ONE of several conditions (OR logic), put each condition in a separate filterGroup. 4. You can include a maximum of five filterGroups with up to 6 filters in each group, with a maximum of 18 filters in total.

🛡️ 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.

🎯 Purpose: 1. Retrieves valid association types between specific HubSpot object types. 📦 Returns: 1. Array of valid association definitions with type IDs, labels, and categories. 🧭 Usage Guidance: 1. Always use before creating associations to ensure valid relationship types or to help troubleshoot association creation errors.

🎯 Purpose: 1. Retrieves existing relationships between a specific object and other objects of a particular type. 2. For example, you can find all companies that a contact is associated with, all deals related to a company, or discover which customers have an open ticket. 📦 Returns: 1. Collection of associated object IDs and relationship metadata. 2. Use hubspot-batch-read-objects to get more information about the associated objects. 🧭 Usage Guidance: 1. Use this tool when mapping relationships between different HubSpot objects to understand your data's connections. 2. This tool is ideal when you already know a specific record's ID and need to discover its relationships with other object types. 3. Prefer this over hubspot-search-objects tool when exploring established connections rather than filtering by properties or criteria.

🛡️ Guardrails: 1. Data Modification Warning: This tool modifies HubSpot data. Only use when the user has explicitly requested to update their CRM. 🎯 Purpose: 1. Creates multiple HubSpot objects of the same objectType in a single API call, optimizing for bulk operations. 📋 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-list-objects tool to sample existing objects for the object type. 3. Use the hubspot-get-association-definitions tool to identify valid association types before creating associations.

🛡️ Guardrails: 1. Data Modification Warning: This tool modifies HubSpot data. Only use when the user has explicitly requested to update their CRM. 🎯 Purpose: 1. Updates multiple existing HubSpot objects of the same objectType in a single API call. 2. Use this tool when the user wants to update one or more existing CRM objects. 3. If you are unsure about the property type to update, identify existing properties of the object and ask the user. 📋 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-list-objects tool to sample existing objects for the object type. 3. If hubspot-list-objects tool's response isn't helpful, use hubspot-list-properties tool.

🎯 Purpose: 1. Retrieves multiple HubSpot objects of the same object type by their IDs in a single batch operation. 🧭 Usage Guidance: 1. Use this tool to retrieve objects when the object IDs are known.

🎯 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.

🎯 Purpose: 1. This tool retrieves detailed information about a specific property for a HubSpot object type. 2. You can use this to get all metadata related to a property, including its type, options, and other configuration details.

🛡️ Guardrails: 1. Data Modification Warning: This tool modifies HubSpot data. Only use when the user has explicitly requested to update their CRM. 🎯 Purpose: 1. Creates new custom properties for HubSpot object types, enabling data structure customization. 📋 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-list-objects tool to sample existing objects for the object type. 3. If hubspot-list-objects tool's response isn't helpful, use hubspot-list-properties tool. 🧭 Usage Guidance: 1. Use this tool when you need to create a new custom property for a HubSpot object type. 2. Makes sure that the user is looking to create a new property, and not create an object of a specific object type. 3. Use list-properties to get a list of all properties for a given object type to be sure that the property does not already exist. 4. Use list-properties to to understand the data structure of object properties first.

🛡️ Guardrails: 1. Data Modification Warning: This tool modifies HubSpot data. Only use when the user has explicitly requested to update their CRM. 🎯 Purpose: 1. Updates existing custom properties for HubSpot object types, enabling data structure customization. 🧭 Usage Guidance: 1. Use hubspot-list-objects tool to sample existing objects for the object type. 2. If hubspot-list-objects tool's response isn't helpful, use hubspot-list-properties tool.

🛡️ Guardrails: 1. Data Modification Warning: This tool modifies HubSpot data. Only use when the user has explicitly requested to update their CRM. 🎯 Purpose: 1. Creates a HubSpot engagement (Note or Task) associated with contacts, companies, deals, or tickets. 2. This endpoint is useful for keeping your CRM records up-to-date on any interactions that take place outside of HubSpot. 3. Activity reporting in the CRM also feeds off of this data. 📋 Prerequisites: 1. Use the hubspot-get-user-details tool to get the OwnerId and UserId. 🧭 Usage Guidance: 1. Use NOTE type for adding notes to records 2. Use TASK type for creating tasks with subject, status, and assignment 3. Both require relevant associations to connect them to CRM records 4. Other types of engagements (EMAIL, CALL, MEETING) are NOT supported yet. 5. HubSpot notes and task descriptions support HTML formatting. However headings (<h1>, <h2>, etc.) look ugly in the CRM. So use them sparingly.

🎯 Purpose: 1. Retrieves a HubSpot engagement by ID.

🛡️ Guardrails: 1. Data Modification Warning: This tool modifies HubSpot data. Only use when the user has explicitly requested to update their CRM. 🎯 Purpose: 1. Updates an existing HubSpot engagement (Note or Task). 2. Allows modification of engagement attributes, content, and metadata. 📋 Prerequisites: 1. You need the engagement ID to update an existing engagement. 2. Use the hubspot-get-engagement tool to get the current engagement details if needed. 3. Use the hubspot-get-user-details tool to get the owner ID. 🧭 Usage Guidance: 1. Use for updating NOTE content or TASK details (subject, description, status). 2. Only include the fields you want to update - other fields will remain unchanged. 3. HubSpot notes and task descriptions support HTML formatting. However headings (<h1>, <h2>, etc.) look ugly in the CRM. So use them sparingly.

🎯 Purpose: 1. Use this tool when the user wants to submit feedback about HubSpot MCP tool. 2. Use this tool proactively when the other HubSpot MCP tools are unable to solve the user's tasks effectively. 3. Use this tool when you sense dissatisfaction from the user using HubSpot MCP tools. 4. Feedback will help us improve the HubSpot MCP tools in future iterations.

🎯 Purpose: 1. Retrieves all custom object schemas defined in the HubSpot account. 🧭 Usage Guidance: 1. Before working with custom objects to understand available object types, their properties, and associations. 📦 Returns: 1. Provides the objectTypeId and objectType for each schema. 2. These attributes should be used for this object type instead of "custom" in subsequent requests.

🎯 Purpose: 1. Generates HubSpot UI links for different pages based on object types and IDs. 2. Supports both index pages (lists of objects) and record pages (specific object details). 📋 Prerequisites: 1. Use the hubspot-get-user-details tool to get the PortalId and UiDomain. 🧭 Usage Guidance: 1. Use to generate links to HubSpot UI pages when users need to reference specific HubSpot records. 2. Validates that object type IDs exist in the HubSpot system.

🎯 Purpose: 1. This tool retrieves a paginated list of workflows from the HubSpot account. 🧭 Usage Guidance: 1. Use the "limit" parameter to control the number of results returned per page. 2. For pagination, use the "after" parameter with the value from the previous response's paging.next.after. 3. This endpoint returns essential workflow information including ID, name, type, and status.

🎯 Purpose: 1. This tool retrieves detailed information about a specific workflow from the HubSpot account. 🧭 Usage Guidance: 1. Use the "flowId" parameter to specify which workflow to retrieve. 2. This endpoint returns complete workflow information including actions, enrollment criteria, and scheduling. 3. Use the hubspot-list-workflows tool first to identify the workflow ID you need.

🔄 Refreshes the HubSpot OAuth access token using the refresh token from environment variables. 🎯 Purpose: - Use only when HubSpot API requests fail due to expired tokens. - Automatically refreshes and sets the active access token in process.env.PRIVATE_APP_ACCESS_TOKEN. - Not required for long-lived Private App tokens. 🛡️ Guardrails: - Only use if using OAuth (i.e. REFRESH_TOKEN is present in environment). - Do not invoke more than once per session unless a 401 Unauthorized response is received from HubSpot API.