HubSpot
OfficialAccess and interact with HubSpot CRM data including contacts, companies, deals, and tickets.
Tools (13)
search_crm_objects
Searches and retrieves CRM records from HubSpot based on filters and criteria. <capabilities> - Returns a 'total' count attribute that can help perform analytical tasks on large datasets - Useful to sample data from a specific object type to understand the data model - Can list and filter by associations between objects (e.g., "contacts associated with company X or contacts with num_associated_deals > 1") - Use the search_owners tool to list users/owners in the HubSpot account </capabilities> <returns> List of matching CRM records containing: - id: Unique identifier for the CRM object - properties: Key-value pairs of property names and their values for the requested properties - urlTemplate: URL template to view the object in HubSpot (replace {property_name} with the property value from the response) - total: Total count of records matching the search criteria (for analytics and pagination) - offset: Current pagination offset for retrieving the next page of results </returns> <usage_guidance> - This searches for ACTUAL DATA (records), not field definitions. To discover available fields, use search_properties - Always check 'total' count to ensure you're not missing data due to pagination limits. You MUST NOT use sample data or insufficient data as a substitute for actual data - Use the `get_crm_objects` without properties to understand the data model of an objectType - You can include a maximum of five filterGroups with up to 6 filters in each group, with a maximum of 18 filters in total - [Important] CRM Analysis can be a complex task. Work with the user to refine requirements and segment large datasets into manageable parts before performing analysis - [Important] You MUST include a clickable URL for every record returned, without exception. ALWAYS include UTM params in the URL - [Important] You should use `associatedWith` for searching objects by associations - [Important] When the user uses first-person language ("I", "my", "me") referring to records they own (e.g. "my deals", "money I brought in", "contacts I own"), you MUST filter by `hubspot_owner_id = {ownerId}` where ownerId comes from get_user_details. Fetching the ownerId without applying it as a filter will return all account records, not the user's own records. </usage_guidance>
submit_feedback
Collects and submits feedback to HubSpot on dissatisfaction or user request. <when_to_invoke> <agent_detected_signals> - User provides explicit correction: "No, I meant...", "Actually, I want..." - User repeats query with different phrasing - User states something is wrong: "That's wrong", "That's not right" - User clarifies because agent misunderstood - User shows dissatisfaction </agent_detected_signals> <user_initiated_signals> - Explicit feedback requests: "I want to give feedback", "Let me share feedback" - Indirect expressions to HubSpot: "HubSpot should know...", "Tell HubSpot..." - Any clear intent to communicate feedback to HubSpot </user_initiated_signals> </when_to_invoke> <agent_detected_flow> 1. Complete your response FIRST (provide the corrected answer) 2. At the END of your response, add a divider line (---) then on a NEW LINE, include ALL of these elements: a) Acknowledge what triggered this: "I noticed [you had to correct that / you expressed frustration]" b) Offer feedback collection: "Want to share feedback on the connector?" c) Make it optional: "Just ask anytime — I'll send it to HubSpot." 3. If user opts in: Follow the same flow as user-initiated (steps 2-3) 4. If user declines or doesn't respond: Continue conversation normally. Never ask again this session. </agent_detected_flow> <user_initiated_flow> 1. Acknowledge immediately: "Happy to help with that. What would you like to share with HubSpot?" 2. If feedback is vague: "Can you be more specific about [specific aspect]? That helps HubSpot improve things." 3. Once you have clear feedback, submit the tool immediately and confirm: "Thanks. Sent to HubSpot — here's a summary of what I sent: [brief summary]. Share more anytime." </user_initiated_flow> <critical_requirements> - NEVER suggest clicking Claude/ChatGPT thumbs up/down buttons sends feedback to HubSpot. Those buttons send feedback to Anthropic/OpenAI only. ONLY this tool sends feedback to HubSpot. </critical_requirements>
get_campaign_contacts_by_type
Get paginated contact IDs for a campaign filtered by attribution type. contactType options: NEW_CONTACTS_FIRST_TOUCH (first marketing interaction was this campaign), NEW_CONTACTS_LAST_TOUCH (last interaction before conversion), INFLUENCED_CONTACTS (any engagement within the date range). Returns contact VIDs usable with CRM tools. Date range is optional (ISO 8601 YYYY-MM-DD); omit for full campaign lifetime. Pagination: offset-based, limit 100–500.
search_owners
Lists and searches for owners who can be assigned to CRM records. <capabilities> - Supports searching by name/email or batch lookup by owner IDs - HubSpot owner ids and user IDs are distinct, lookups only work when owner ids are provided specifically </capabilities> <returns> List of owner objects containing: - ownerId: The ID to use for hubspot_owner_id assignments - name: Display name of the owner - isActive: Whether the owner is currently active </returns> <examples> <example> <description>Search by name</description> <query>{"searchQuery": "John Smith"}</query> </example> <example> <description>Lookup specific IDs</description> <query>{"ownerIds": [12345, 67890]}</query> </example> <example> <description>Paginate results</description> <query>{"limit": 50, "offset": 50}</query> </example> </examples>
get_campaign_analytics
Get campaign analytics (METRICS or REVENUE_ATTRIBUTION) for one or more campaigns. Each entry in the request list is a full analytics request. Each response contains the campaignObjectId of the requested campaign.
get_campaign_asset_types
List the asset type names available as campaign assets (e.g. LANDING_PAGE, BLOG_POST). Use the returned names as the assetType parameter in getCampaignAssetMetrics.
get_organization_details
Lists organization-wide teams, job titles (roles), seats, and account information (eg timezone, currency). Use the include parameter to request only the data you need. <returns> - GUIDANCE (optional): Returned if additional context is required so provide a useful response Only fields listed in the include parameter are returned (or all fields if include is omitted): - TEAMS: Team objects with name, member's owner IDs, and metadata (org-wide, not personal — for the current user's team use get_user_details with include=[TEAMS_AND_ROLES]) - SEATS: Available seat type names in the organization (use these as filters with search_crm_objects on USER objectType to count how many users hold each seat) - JOB_TITLES: Job titles/roles present in the organization - ACCOUNT_INFORMATION: Account timezone, currency, account type, and UI domain </returns> <usage_guidance> - IMPORTANT: Check if user query contains first-person language ("my team", "my role", "my manager", "my direct reports") - If query uses "my", "I", or "me" referring to personal context → Use get_user_details instead - EXCEPTION: "my teams" or "which teams am I on" (plural) should use this tool since get_user_details only returns a single primaryTeam - If query is organization-wide ("our marketing team", "the sales team", "all managers", "my teams") → Use this tool - Use the include parameter to fetch only what you need and reduce response size - Include TEAMS when you need team membership or structure - Include SEATS when you need available seat types - Include JOB_TITLES when you need roles/job titles to filter users by role - Include ACCOUNT_INFORMATION when you need the account's timezone, currency, account type, or UI domain - To find or count users by role or seat, use the returned job titles or seat types as filters with search_crm_objects on USER objectType - SEATS returns only seat type names, not user counts — you MUST follow up with search_crm_objects to get user counts per seat type - When the user references a team's data (e.g., 'our sales team's deals', 'marketing team pipeline'), use this tool first with include=[TEAMS] to resolve team membership to owner IDs, then pass those IDs as filters to search_crm_objects. - To find "my teams" (plural), call this tool with include=[TEAMS] and find teams with the user's ownerId -- [IMPORTANT]: DO NOT use member name for matching, only use ownerId - [IMPORTANT] If the `guidance` field is present, read it carefully before responding — it may contain a user-facing message (e.g., missing permissions requiring reauthorization) that must be relayed to the user, or an agent-internal hint (e.g., name disambiguation) that should influence how you process the results </usage_guidance> <examples> <example> <user_query>Who works in sales at my company?</user_query> <action>Use this tool with include=[TEAMS] to get teams, then filter for sales-related ones</action> </example> <example> <user_query>Show me deals for MY team?</user_query> <action>Do NOT use this tool, use get_user_details instead</action> </example> <example> <user_query>Search deals for all marketers</user_query> <action>Use this tool with include=[JOB_TITLES] to find marketing-related roles</action> </example> <example> <user_query>How many users have each seat type?</user_query> <action>Use this tool with include=[SEATS] to get seat type names, then use search_crm_objects on USER objectType filtering by each seat type to count users per seat</action> </example> <example> <user_query>Show me our sales team's deal pipeline</user_query> <action>Use this tool with include=[TEAMS] to get the sales team's member owner IDs, then use search_crm_objects to filter deals by those owner IDs.</action> </example> <example> <user_query>Which teams am I on?</user_query> <action>Use this tool with include=[TEAMS] to get all teams, then find teams that contain the member's ownerID (NOT MEMBER'S NAME)</action> </example> </examples>
get_properties
Fetches property definitions including data types and enumeration values. <capabilities> - Particularly useful for discovering valid options in enumeration-type properties - To search for actual data, use search_crm_objects </capabilities> <returns> List of property definition objects containing: - name: Property identifier - label: Display label - description: Property description - type: Data type (string, enumeration, number, etc.) - options: For enumeration types, list of valid values with labels </returns> <usage_guidance> - Property details can be unexpectedly large. Consider fetching in batches - It's not advised to pass an objects full list of properties into this tool </usage_guidance>
get_campaign_asset_metrics
Get metrics and properties for specific CRM objects associated with a campaign. campaignObjectId, assetType, and crmObjectIds are all required. Search the campaign's associated objects for objects of the given asset type to retrieve their CRM object IDs, then pass those IDs here. assetType is a name (e.g. MARKETING_EMAIL) — call getCampaignAssetTypes to get the full list. Optional date range (ISO 8601 YYYY-MM-DD) to populate date range metrics.
search_properties
Finds the most relevant CRM property definitions using keyword-based search. <capabilities> - Lists all property definitions for specified object type when no search terms provided - To search for actual data, use search_crm_objects </capabilities> <returns> A filtered list of properties matching the search criteria containing: - name: Property identifier - label: Display label - description: Property description - matchScore: Relevance score for the property based on the search query (absent if no query is provided) </returns> <usage_guidance> - Use keywords field for multiple related property guesses in a SINGLE request (recommended for performance) - MAXIMUM OF 5 KEYWORDS ALLOWED PER REQUEST - exceeding this limit will return a validation error - Keywords should be property name guesses, not natural language phrases - Use query field for backward compatibility with single property guess - No search terms provided: Returns ALL properties for the object type (useful for discovery) </usage_guidance> <examples> <example> <user_input>total number of open tickets grouped by urgency</user_input> <thoughts>Customer is asking for total number of open tickets grouped by "urgency". I will look for the best matches on the "urgency" property for the "TICKET" object type.</thoughts> <query>{"objectType": "TICKET", "keywords": ["urgency"]}</query> </example> <example> <user_input>calls assigned to me</user_input> <thoughts>Customer is asking us to filter by calls assigned to them. I have a few guesses for what that property might be called: "assigned_to", "assignee", "owned_by", or "owner". Let me search for those on the "CALL" object type in one efficient request.</thoughts> <query>{"objectType": "CALL", "keywords": ["assignee", "assigned_to", "call_owner", "owned_by"]}</query> </example> <example> <user_input>list each company with its name, employees amount, zip code, and when we last touched base</user_input> <thoughts>Customer is asking us to list companies by a few attributes. I will guess keywords for each of those properties and search for them on the "COMPANY" object type in one request.</thoughts> <query>{"objectType": "COMPANY", "keywords": ["name", "employees", "zip_code", "last_contact"]}</query> </example> <example> <user_input>tickets for this year to identify top 10 most problems our customers face</user_input> <thoughts>Customer is asking us to analyze tickets. I will return all properties for the "TICKET" object type to help with discovery.</thoughts> <query>{"objectType": "TICKET"}</query> </example> </examples> <common_mistakes> - Do not exceed 5 keywords per request (will return validation error) - Keywords should be property name guesses, not natural language phrases </common_mistakes>
get_crm_objects
Fetches multiple CRM objects of the same object type in a single request. <returns> A list of CRM objects with their properties, identified by their unique IDs, containing: - id: Unique identifier for the CRM object - properties: Key-value pairs of property names and their values - createdAt: Timestamp when the object was created - updatedAt: Timestamp when the object was last updated - url: URL to view the object in HubSpot </returns> <usage_guidance> - Use the `search_crm_objects` tool to list a few objects first without a filter criteria - Then use the `get_crm_objects` tool to retrieve those objects by their IDs without any properties in the tool input to understand the data model - This will help you understand the structure of the objects and their properties </usage_guidance>
get_user_details
Returns user, team and hub info; CRM/marketing object and tool availability. <usage_guidance> - 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 - This tool only return information for the current user. Search for "users" objectType using the search_crm_objects tool to find other users/owners in the HubSpot account - This tool provides the availability of crm object types to the current user. Use these values in tools which expect crm object type parameters - This tool provides more accurate availability of the other tools provided by this MCP service. This is critical when tool returned in the response is not `AVAILABLE` - Every non `AVAILABLE` object type or tool requires some user interaction to resolve, noting that some issues cannot be resolved by just the user themselves - Each object type returns TWO separate availability statuses: `read` for view/search operations and `write` for create/update operations. Check the appropriate permission based on the operation you intend to perform - Use the "include" param to request only the sections you need; omitting it or passing an empty list returns USER_INFORMATION and TOOL_INFORMATION only — TEAMS_AND_ROLES must be explicitly requested - For account-level settings (timezone, currency, account type, UI domain), use get_organization_details with include=[ACCOUNT_INFORMATION] instead of this tool - TEAMS_AND_ROLES returns context specific to the current user only (their primary team, job title, direct reports); for org-wide team or role data, including "my TEAMS", use get_organization_details - IMPORTANT: directReports are not the same as team members. If directReports is empty and the user asked about direct reports: stop, inform the user that no direct reports are configured, and ask whether they want to proceed with team members instead — do not automatically substitute team members for direct reports </usage_guidance> <availability_guidance> <status name="AVAILABLE">It is free to use without issue</status> <status name="REQUIRES_REAUTHORIZATION">The user needs to perform a new authorization flow through HubSpot to unlock new access. This is possible through disconnecting and reconnecting the HubSpot connector through their settings</status> <status name="REQUIRES_PERMISSION_MODIFICATION">The user lacks the correct permission in their HubSpot account. If the only way to resolve a task is to use this tool or object, you should inform the user of their lacking permissions and let them decide if they want to ask their administrator for more privilege</status> <status name="REQUIRES_ACCOUNT_MODIFICATION">The whole HubSpot account lacks the correct permissions and would require an account upgrade. Again, inform the user about these tools or objects only if the presented task can only be solved using them</status> <status name="BLOCKED_FOR_PORTALS_WITH_SENSITIVE_DATA">The operation involves sensitive data, and no troubleshooting will unblock usage of the object or tool. If the only way to resolve a task is to use this tool or object, inform the user of the issue and ask them how they would like to proceed</status> <status name="NOT_AVAILABLE">There is no action the user can take to enable the object or tool. It is simply unavailable for use</status> </availability_guidance> <returns> - Always returned: user ID and Hub ID (accountId) - Only fields listed in the include parameter are returned (or all fields if include is omitted): - USER_INFORMATION: owner ID, name, and email for the current user - TOOL_INFORMATION: a mapping of CRM object types to separate `read` and `write` availability statuses; a mapping of other MCP tools to current availability - TEAMS_AND_ROLES: the current user's job title, assigned seats, primary team with member owner IDs, and direct report owner IDs (personal context only — use get_organization_details for org-wide team/role data) - If the `guidance` field is present, STOP and relay its message to the user — it indicates requested sections could not be returned and the user needs to reauthorize the app </returns> <examples> <example> <user_query>Compare workload across my direct reports</user_query> <action>Call with include=[TEAMS_AND_ROLES]. If directReports is empty, ask the user if they would like to compare workload across their primary team members instead. DO NOT use team members unless user confirms.</action> </example> </examples>
tool_guidance
<purpose> Retrieves guidance and usage instructions for a set of HubSpot tools. </purpose> <when_to_use> - If a tool's description isn't enough to commit to using it - To find if a tool's inputs or outputs have further semantic meaning - To learn understand if and how certain tools can work together </when_to_use>