HubSpot

Activate a workflow (sets isEnabled to true).

Add records to a HubSpot list/segment. USE THIS WHEN: - User asks "add these contacts to the Q3 webinar list" or "put this deal on the nurture list" WORKFLOW: 1. list_hubspot_lists → find the listId 2. search_hubspot_contacts (or another search tool) → find the record IDs 3. add_hubspot_list_members with both IMPORTANT: only MANUAL and SNAPSHOT lists accept membership changes. DYNAMIC lists compute membership from their filter criteria — HubSpot rejects the write; edit the list's filters (in the HubSpot UI) instead. REQUIRES the crm.lists.write OAuth scope. On a 403 the account's plan, the signed-in user's permissions, or the connected app's scopes are the likely cause.

Upload a file and attach it to a CRM record in one step. This is a convenience tool that combines: 1. Uploading a file to HubSpot's file manager 2. Creating a note with the file attached 3. Associating the note with the specified record(s) USE THIS WHEN: - User says "attach this file to [contact/deal/company]" - Adding a document, proposal, or contract to a record - Uploading meeting notes or attachments to a contact ACCEPTS EITHER: - filePath: Local file path to upload - fileUrl: Public URL to import RETURNS: { fileId, noteId, fileName, associations }

Connect a new HubSpot account or re-authenticate an existing one. This tool initiates the OAuth flow to connect a HubSpot account: 1. Returns an authorization URL that the user must click 2. User signs into HubSpot and grants permissions 3. Authentication completes automatically via callback WHEN TO USE: - When list_hubspot_accounts shows no connected accounts - When an account shows status "expired" or "error" - When user explicitly asks to connect/reconnect HubSpot WHEN NOT TO USE: - If list_hubspot_accounts shows a valid, active account - Without checking list_hubspot_accounts first (wastes user time) After calling this tool: 1. Present the auth_url to the user as a clickable link 2. Tell them to click it and authorize in their browser 3. Call complete_hubspot_auth to wait for completion 4. Or if auto_complete is enabled, it will complete automatically

Fetch multiple contacts by ID in a single request (up to 100). USE THIS TO: Hydrate contact IDs from list_hubspot_list_members into full records. WORKFLOW: 1. list_hubspot_list_members(listId) → get recordIds 2. batch_read_hubspot_contacts(ids, ['email', 'firstname', 'lastname']) → get details RETURNS: {results: [{id, properties: {email, firstname, ...}, createdAt, updatedAt}]} Common properties: email, firstname, lastname, phone, company, jobtitle, lifecyclestage

Wait for HubSpot OAuth authorization to complete. Call this AFTER authenticate_hubspot_account has returned an auth_url and the user has clicked it. This tool: 1. Waits for the OAuth callback (up to 2 minutes) 2. Exchanges the authorization code for access tokens 3. Saves the account credentials 4. Returns success with the connected email IMPORTANT: Only call this if auto_complete was false in authenticate_hubspot_account response. If auto_complete was true, authentication completes automatically and you don't need this tool.

Create an unlabeled association between two HubSpot objects (v3 API). For labeled associations (e.g., "Primary Contact", "Contract Signatory", "Decision Maker"), use create_hubspot_labeled_association instead. Common association types: - contact_to_company - deal_to_contact - deal_to_company - ticket_to_contact - line_item_to_deal

Log a call in HubSpot CRM. USE THIS WHEN: - User says "log a call" or "record that I called [contact]" - Documenting a phone conversation - Adding call notes after a conversation REQUIRED: hs_timestamp (Unix timestamp in milliseconds) COMMON PROPERTIES: - hs_timestamp: when call occurred (REQUIRED, Unix ms, e.g., Date.now()) - hs_call_title: brief description - hs_call_body: notes, transcript, or summary - hs_call_direction: "INBOUND" or "OUTBOUND" - hs_call_status: "COMPLETED", "BUSY", "NO_ANSWER", "FAILED" - hs_call_duration: call length in milliseconds - hubspot_owner_id: who made the call ASSOCIATIONS (link call to records): - contactIds: ["contact_id_1", "contact_id_2"] - companyIds: ["company_id"] - dealIds: ["deal_id"] WORKFLOW: 1. search_hubspot_contacts to get contact ID 2. create_hubspot_call with associations.contactIds RETURNS: Created call with id

Create a new company in HubSpot CRM. USE THIS WHEN: - User says "add company" or "create account for [organization]" - Company doesn't exist (verify with search first!) REQUIRED: name COMMON PROPERTIES: - name (company name) - domain (website domain, used for deduplication) - industry (e.g., "COMPUTER_SOFTWARE", "FINANCIAL_SERVICES") - numberofemployees, annualrevenue - phone, address, city, state, zip, country - hubspot_owner_id: assign to team member (RECOMMENDED — get IDs from list_hubspot_owners) COMMON MISTAKES: - NOT specifying hubspot_owner_id — if omitted, the company may be assigned to the HubSpot integration account used by your host, not the intended owner. Use list_hubspot_owners to find the correct owner ID. - If list_hubspot_owners returns empty (e.g., free accounts), you may proceed without hubspot_owner_id. RETURNS: Created company with id and properties

Create a new contact in HubSpot CRM. USE THIS WHEN: - User says "add contact" or "create contact for [person]" - Logging a new lead or prospect - Contact doesn't exist (verify with search first!) REQUIRED: email (strongly recommended - used for deduplication) NOTE: The server automatically sets hs_object_source_detail_2 for source attribution. COMMON PROPERTIES: - email, firstname, lastname - phone, mobilephone - company, jobtitle - address, city, state, zip, country - lifecyclestage: "lead", "marketingqualifiedlead", "salesqualifiedlead", "opportunity", "customer" - hubspot_owner_id: assign to a team member (RECOMMENDED — get IDs from list_hubspot_owners) COMMON MISTAKES: - NOT specifying hubspot_owner_id — if omitted, the contact may be assigned to the HubSpot integration account used by your host, not the intended owner. Use list_hubspot_owners to find the correct owner ID. - If list_hubspot_owners returns empty (e.g., free accounts), you may proceed without hubspot_owner_id. RETURNS: Created contact with id and properties

Create a new deal/opportunity in HubSpot CRM. USE THIS WHEN: - User says "create deal" or "add opportunity" - Logging a new sales opportunity REQUIRED: dealname, hubspot_owner_id IMPORTANT: Use list_hubspot_pipelines first to get valid pipeline and dealstage IDs! FALLBACK FIELDS (set by the server only if not provided): - hubspot_owner_id: FALLBACK ONLY — if not provided via the top-level parameter, falls back to the HubSpot integration account used by your host. This is usually the WRONG person on team accounts. - hs_object_source_detail_2: records that this deal was created via your MCP host COMMON PROPERTIES (inside the properties object): - dealname (deal/opportunity name) - amount (deal value as string, e.g., "10000") - pipeline (pipeline ID from list_hubspot_pipelines, e.g., "default") - dealstage (stage ID from list_hubspot_pipelines, e.g., "qualifiedtobuy") - closedate (expected close date, format: "YYYY-MM-DD") WORKFLOW: 1. list_hubspot_pipelines to get pipeline/stage IDs 2. list_hubspot_owners to find the correct deal owner 3. create_hubspot_deal with valid pipeline/stage IDs AND hubspot_owner_id 4. create_hubspot_association to link to contact/company COMMON MISTAKES: - Using this tool when the user says "lead" or "create a lead" — leads are a separate HubSpot object type. Use create_hubspot_lead instead. - NOT specifying hubspot_owner_id — if omitted, the deal is silently assigned to the HubSpot integration account used by your host, NOT the intended deal owner. This causes incorrect assignment notifications and pipeline confusion. ALWAYS call list_hubspot_owners to find the correct owner ID. - Using display names instead of IDs for pipeline/dealstage — always use list_hubspot_pipelines to get valid IDs first. RETURNS: Created deal with id and properties

Create a labeled association between two records using the v4 API. Unlike create_hubspot_association (v3, unlabeled), this creates associations WITH labels like "Primary Contact", "Contract Signatory", "Decision Maker", etc. WORKFLOW: 1. Call list_hubspot_association_labels to discover available labels and their typeIds 2. Call this tool with the desired associationCategory and associationTypeId associationCategory: - "HUBSPOT_DEFINED": Built-in labels (e.g., Primary Contact, typeId varies by object pair) - "USER_DEFINED": Custom labels created in HubSpot Settings → Objects → Associations

Create a new lead in HubSpot CRM. NOTE: Requires Sales Hub Professional or Enterprise. IMPORTANT: This tool creates a HubSpot Lead object (pipeline/stage tracking in Sales Hub). DO NOT use create_hubspot_deal when the user says "lead" — deals and leads are separate HubSpot object types. REQUIRED: - properties.hs_lead_name (the lead's display name) - contactId (leads MUST be associated with a contact at creation — HubSpot API requirement) The contactId is used to create a LEAD_TO_PRIMARY_CONTACT association automatically. COMMON PROPERTIES: - hs_lead_name (required — lead display name) - hs_lead_status: "NEW", "OPEN", "IN_PROGRESS", "CONNECTED", "ATTEMPTED_TO_CONTACT" - hubspot_owner_id: assign to a team member (get IDs from list_hubspot_owners) WORKFLOW: 1. search_hubspot_contacts to find/create the contact 2. create_hubspot_lead with contactId and properties 3. Optionally create_hubspot_association to link to a company or deal RETURNS: Created lead with id and properties

Create a line item and optionally associate with a deal. Line items link products to deals for revenue tracking. This is the KEY tool for adding products to a deal. WORKFLOW: 1. search_hubspot_products to find product ID 2. search_hubspot_deals to find deal ID 3. create_hubspot_line_item with dealId association REQUIRED PROPERTIES: - name: Line item name - quantity: Number of units (string, e.g. "1") - price: Unit price (string, e.g. "1000.00") OPTIONAL: - hs_product_id: Link to product catalog - hs_discount_percentage: Discount to apply - dealId: Associate immediately with deal EXAMPLE: { "properties": { "name": "Enterprise License - Annual", "quantity": "2", "price": "10000", "hs_product_id": "123456" }, "dealId": "789" } RETURNS: Created line item with id

Log a meeting in HubSpot CRM. USE THIS WHEN: - User says "log a meeting" or "record meeting with [contact]" - Documenting a completed meeting - Scheduling a future meeting in CRM REQUIRED: - hs_timestamp (Unix ms) - hs_meeting_start_time (Unix ms) - hs_meeting_end_time (Unix ms) COMMON PROPERTIES: - hs_timestamp: when meeting was logged (Unix ms) - hs_meeting_start_time: meeting start (Unix ms) - hs_meeting_end_time: meeting end (Unix ms) - hs_meeting_title: meeting subject - hs_meeting_body: notes, agenda, or action items - hs_meeting_outcome: "SCHEDULED", "COMPLETED", "RESCHEDULED", "NO_SHOW", "CANCELLED" - hs_meeting_location: location or video link - hubspot_owner_id: meeting organizer ASSOCIATIONS (link meeting to records): - contactIds: attendee contact IDs - companyIds: company IDs - dealIds: related deal IDs WORKFLOW: 1. search_hubspot_contacts to get attendee contact IDs 2. create_hubspot_meeting with associations RETURNS: Created meeting with id

Create a note in HubSpot and optionally associate it with records. Properties: - hs_note_body (required) - The note content (supports HTML) - hs_timestamp - When the note was created (ISO8601 or Unix ms) - hs_attachment_ids - Semicolon-separated file IDs to attach (e.g., "123" or "123;456") Get file IDs from upload_hubspot_file or import_hubspot_file_from_url. TO ATTACH FILES TO A RECORD: 1. Upload file with upload_hubspot_file → get file id 2. Create note with hs_attachment_ids: "<file_id>" and associations to the record Or use the convenience tool attach_file_to_record for a one-step workflow.

Create a record of ANY HubSpot object type, including custom objects. Use list_hubspot_properties with the same objectType first to discover the object's properties and their expected values. To link the new record to other records, follow up with create_hubspot_association (or create_hubspot_labeled_association). REQUIRES the crm.objects.custom.write OAuth scope for custom object types.

Create a new product in the product catalog. USE THIS WHEN: - Adding new products to sell - Setting up product catalog REQUIRED: name RECOMMENDED: price, hs_sku, description EXAMPLE: { "properties": { "name": "Enterprise License", "price": "10000", "hs_sku": "ENT-001", "description": "Annual enterprise license" } } RETURNS: Created product with id

Create a new custom property on a HubSpot object. VALID TYPE/FIELDTYPE COMBINATIONS: - string: text, textarea, phonenumber, html - number: number - date: date - datetime: date - enumeration: select, radio, checkbox, booleancheckbox - bool: booleancheckbox

Create a new property group for an object type

Create a new task in HubSpot. Common properties: - hs_task_subject (required) - hs_task_body - hs_timestamp (due date in ms) - hs_task_status (NOT_STARTED, IN_PROGRESS, COMPLETED) - hs_task_priority (LOW, MEDIUM, HIGH) - hubspot_owner_id

Create a new ticket in HubSpot. Common properties: - subject (required) - content - hs_pipeline - hs_pipeline_stage - hs_ticket_priority

Create a new HubSpot workflow. ⚠️ BETA API — this uses the v4 Automation API. Endpoint behavior may change. WORKFLOW TYPES: - CONTACT_FLOW: Triggered by contact enrollment - COMPANY_FLOW: Triggered by company enrollment - DEAL_FLOW: Triggered by deal enrollment - TICKET_FLOW: Triggered by ticket enrollment EXAMPLE minimal workflow: { "name": "New Lead Notification", "type": "CONTACT_FLOW" } To add actions and enrollment criteria, use the fields from get_hubspot_workflow as a reference for the expected structure.

Deactivate a workflow (sets isEnabled to false).

Remove an association between two objects

Permanently delete a company from HubSpot. WARNING: This is permanent and may affect associated contacts and deals. PREREQUISITE: Get companyId from search_hubspot_companies first

Permanently delete a contact from HubSpot. USE THIS WHEN: - User explicitly asks to delete/remove a contact - Cleaning up duplicate or test records WARNING: This is permanent. Associated engagements may be orphaned. PREREQUISITE: Get contactId from search_hubspot_contacts first

Permanently delete a deal from HubSpot. WARNING: This is permanent. Deal history and associations will be lost. PREREQUISITE: Get dealId from search_hubspot_deals first

Delete a file from HubSpot's file manager. WARNING: This marks the file as deleted and makes its content inaccessible. Notes that reference this file will no longer display the attachment.

Permanently delete a lead from HubSpot. NOTE: Requires Sales Hub Professional or Enterprise. WARNING: This is permanent. The lead record will be removed. PREREQUISITE: Get leadId from search_hubspot_leads first

Permanently delete (archive) a note by ID. This cannot be undone from the CRM UI recycle bin for engagements — confirm with the user first.

Archive a property from HubSpot. This ARCHIVES the property (not a hard delete).

Delete a task from HubSpot

Delete a ticket from HubSpot

Permanently delete a workflow. WARNING: This is irreversible. The workflow and its history are removed. Set confirm=true to acknowledge permanent deletion.

Enrol specific records into a workflow. Uses the v4 BETA enrollment endpoint. A 403 means the connection can't access workflows (most often plan or user permissions, less commonly app authorisation) — reconnecting alone won't fix it; resolve the cause, then reconnect. A 404 may mean your portal requires the v3 enrollment endpoint.

Get all recent activity (calls, meetings) for a contact. USE THIS WHEN: - User asks "what's the history with [contact]?" or "show activity for [person]" - Preparing for a meeting and need relationship context - Need a quick activity summary RETURNS: Object with arrays for each engagement type: { calls: [{id, properties}], meetings: [{id, properties}] } This is a convenience tool that fetches multiple engagement types in one call. For more control, use search_hubspot_calls or search_hubspot_meetings directly. PREREQUISITE: Get contactId from search_hubspot_contacts first

Get website traffic analytics report. This is the ONLY reporting API available from HubSpot. HubSpot does not have a public API for creating, listing, or managing custom reports or dashboards. For custom report needs, users must use the HubSpot UI directly. ⚠️ REQUIRES Marketing Hub Professional or Enterprise. Will return 403 error on free accounts. BREAKDOWN OPTIONS: - totals: Overall traffic metrics - sessions: Session-based metrics - sources: Traffic by source (organic, direct, etc.) - geolocation: Traffic by country/region - utm-campaigns: By UTM campaign - utm-sources: By UTM source - utm-mediums: By UTM medium - pages: By page URL TIME PERIODS: - totals: Aggregate for date range - daily: Day-by-day breakdown - weekly: Week-by-week - monthly: Month-by-month DATE FORMAT: YYYYMMDD (e.g., "20260101") RETURNS: { totals: {views, visits, leads, ...}, breakdowns: [{breakdown: "...", metrics: {...}}, ...] }

Get all associations of a specific type for an object. Useful for pivoting between object types in either direction, e.g.: - deal -> contacts / companies / line_items - line_item -> deals (resolves a line item back to its parent deal) - ticket -> contacts / companies - contact -> deals / companies RETURNS: { results: [{ id, type }] } — array of associated record IDs.

Get full details for a single call by ID. USE THIS WHEN: - You have a call ID and need complete details - Retrieving call notes or recording info PREREQUISITE: Get callId from search_hubspot_calls or get_contact_engagements

Get full details for a single company by ID. USE THIS WHEN: - You have a company ID (from search or association) - Need complete company profile for account research PREREQUISITE: Get companyId from search_hubspot_companies or get_hubspot_associations

Get full details for a single contact by ID. USE THIS WHEN: - You already have a contact ID (from search or association) - Need complete contact information - Preparing a detailed contact profile RETURNS: Single contact object with all requested properties PREREQUISITE: Get contactId from search_hubspot_contacts first

Get full details for a single deal by ID. USE THIS WHEN: - You have a deal ID (from search or association) - Need complete deal information including custom properties PREREQUISITE: Get dealId from search_hubspot_deals or get_hubspot_associations

Get full details for a single logged email engagement by ID. PREREQUISITE: Get emailId from search_hubspot_emails or get_contact_engagements. SCOPE NOTE: the email body (hs_email_text / hs_email_html) is redacted by HubSpot unless the connected app holds the sales-email-read scope; the response carries a notes field warning when redaction applies. Subject, sender, recipients, and timestamps are always returned.

Get aggregated email performance statistics. RETURNS: { aggregations: {sent, delivered, opened, clicked, bounced, unsubscribed}, emails: [{emailId, counters: {...}}] } Use this to analyze email campaign performance across multiple emails.

Get details of a file in HubSpot's file manager by ID. USE THIS WHEN: - Need to check file details (name, size, URL, access level) - Verifying a file exists before attaching to a record - Getting a viewable URL for a private file (use getSignedUrl: true) RETURNS: { id, name, path, url, size, type, access, createdAt, updatedAt } For private files, the url will 404. Set getSignedUrl to true to get a temporary viewable URL.

Get detailed information about a specific form. RETURNS: Form with id, name, configuration, fieldGroups (form fields)

Get submissions for a specific form. USE THIS WHEN: - Reviewing lead capture performance - Checking recent form submissions - Analyzing lead sources RETURNS: Array of submissions with: - submittedAt: Submission timestamp - values: Field name/value pairs - pageUrl: Where form was submitted NOTE: Uses formGuid (same as formId for most forms)

Get full details for a single HubSpot Knowledge Base article by ID via the GraphQL API (read-only). USE THIS WHEN: - You already have an articleId and need full content/details - Need the complete article body, metadata, or URL RETURNS: - Full KB article object with id, title, body, slug, URL, language, and metadata WORKFLOW: 1. Get articleId from list_hubspot_kb_articles or search_hubspot_kb_articles 2. Call get_hubspot_kb_article for complete details SCOPES REQUIRED: cms.knowledge_base.articles.read and collector.graphql_query.execute (a 403 usually means the account's plan or the signed-in user's permissions don't include the knowledge base — reconnecting alone won't add it) COMMON MISTAKES: - Using a knowledgeBaseId/contentGroupId instead of an articleId - Assuming search result snippets are full article content — use this tool for the full body Requires Service Hub Professional or Enterprise.

Get full details for a single lead by ID. NOTE: Requires Sales Hub Professional or Enterprise. USE THIS WHEN: - You already have a lead ID (from search or association) - Need complete lead information - Reviewing a specific lead's properties and status RETURNS: Single lead object with all requested properties PREREQUISITE: Get leadId from search_hubspot_leads first