HubSpot Integration Conduit Documentation

This conduit server bridges the capabilities of the HubSpot API, allowing the AI agent to perform sophisticated data querying and management operations within the HubSpot CRM environment, specifically targeting sales intelligence enhancement.

Important Notice

This software component operates independently of HubSpot, Inc. It functions solely via documented public APIs and carries no formal endorsement or affiliation with the HubSpot organization.

Available Functions

Fundamental CRM Operations

1. hubspot_search_contacts

2. Executes a lookup for contacts within HubSpot based on a specified search criterion.

3. Mandatory Argument:
   • query (text): The string used for searching (e.g., email address, full name).
4. Optional Arguments:
   • count (integer, default: 10): Limits the returned volume of contact records.
   • propertyList (array of strings): Designates which specific data fields should be included in the output.

5. Output: A collection of matching contact objects detailing their requested attributes.

6. hubspot_get_contact

7. Retrieves the complete details for an individual contact using its unique identifier.

8. Mandatory Argument:
   • contactId (text): The system ID of the target contact.
9. Optional Arguments:
   • properties (array of strings): Specifies the attributes to be fetched.

10. Output: The requested contact record populated with the specified attributes.

11. hubspot_create_contact

12. Provisions a new prospect record within the HubSpot system.

13. Mandatory Argument:
    • properties (dictionary): A map of contact attributes, requiring the presence of the 'email' attribute.

14. Output: Confirmation data for the newly instantiated contact.

15. hubspot_update_contact

16. Modifies the data associated with an existing contact entity.

17. Mandatory Arguments:
    • contactId (text): The identifier of the record to be modified.
    • properties (dictionary): The data fields and their new values for the update.

18. Output: Verification message confirming the successful modification.

19. hubspot_list_deals

20. Fetches a paginated listing of all active sales opportunities.

21. Optional Arguments:
    • limit (integer, default: 10, maximum: 100): Controls the batch size of returned deals.
    • after (text): A pointer used to navigate to the subsequent segment of results.
    • properties (array of strings): Defines which deal attributes to include.

22. Output: A segment of the deal record set with corresponding metadata.

23. hubspot_get_deal

24. Accesses the full profile of a specific sales transaction via its ID.

25. Mandatory Argument:
    • dealId (text): The unique identifier for the sales opportunity.
26. Optional Arguments:
    • properties (array of strings): Attributes to be retrieved for the deal.

27. Output: The complete deal record featuring the requested properties.

28. hubspot_create_deal

29. Establishes a new record for a prospective transaction.

30. Mandatory Argument:
    • properties (dictionary): Deal attributes, mandating the inclusion of the 'dealname' field.

31. Output: Details confirming the successful creation of the deal record.

32. hubspot_update_deal

33. Applies modifications to an existing sales opportunity record.

34. Mandatory Arguments:
    • dealId (text): The ID referencing the opportunity being modified.
    • properties (dictionary): The updated values for the deal properties.

35. Output: A notification confirming the record's updated status.

36. hubspot_list_companies

37. Generates a segmented list of client/prospect organizations.

38. Optional Arguments:
    • limit (integer, default: 10, maximum: 100): Sets the maximum number of organizations returned per call.
    • after (text): Cursor pointing to the next page of results.
    • properties (array of strings): Desired fields to be returned for each company.

39. Output: A collection of organization records.

40. hubspot_get_company

    • Fetches detailed information for a single organization using its system ID.
    • Mandatory Argument:
    • companyId (text): The unique identifier for the organization.
    • Optional Arguments:
    • properties (array of strings): Specific organizational attributes to retrieve.
    • Output: The organization's profile populated with the requested data points.

Sales Performance Intelligence Tools

1. hubspot_get_sales_analytics

   • Computes summarized sales metrics across defined temporal boundaries.
   • Mandatory Arguments:
   • period (text): The aggregation interval (e.g., 'daily', 'monthly', 'quarterly').
   • startDate (text): The initial chronological marker for the analysis (ISO format: YYYY-MM-DD).
   • Optional Arguments:
   • endDate (text): The terminal chronological marker (ISO format).
   • pipeline (text): Identifier to restrict analysis to a specific sales pathway.
   • dealStage (text): Filter based on a particular stage within the pipeline.
   • dealOwner (text): Filter results to a specific sales representative.
   • Output: Sales performance aggregates segmented by the specified time unit.

2. hubspot_get_deal_history

   • Audits and returns the comprehensive log of modifications applied to a transaction.
   • Mandatory Argument:
   • dealId (text): The unique identifier of the sales transaction.
   • Output: A chronological ledger detailing every alteration, including timestamps.

3. hubspot_get_deal_notes

   • Retrieves all textual commentary attached to a specific sales opportunity.
   • Mandatory Argument:
   • dealId (text): The identifier for the deal.
   • Optional Arguments:
   • limit (integer, default: 20): Maximum count of notes to return.
   • after (text): Pagination control for subsequent note sets.
   • Output: A catalog of associated notes, including creation time and content.

4. hubspot_get_engagements_by_deal

   • Fetches all recorded interactions (calls, emails, meetings, tasks) tied to a transaction.
   • Mandatory Argument:
   • dealId (text): The ID of the associated sales opportunity.
   • Optional Arguments:
   • types (array of strings): Filters the interactions by type (e.g., 'CALL', 'EMAIL').
   • limit (integer, default: 20): Maximum interactions to retrieve.
   • after (text): Cursor for fetching the next batch of engagements.
   • Output: A detailed list of interactions linked to the deal.

5. hubspot_get_sales_performance

   • Calculates key performance indicators (KPIs) for sales personnel across a defined timeframe.
   • Mandatory Arguments:
   • period (text): The rotational interval for metric calculation (e.g., 'weekly', 'monthly').
   • startDate (text): The commencement date for performance review (ISO format).
   • Optional Arguments:
   • endDate (text): The conclusion date for the review period (ISO format).
   • ownerIds (array of strings): IDs of sales representatives whose performance is under review.
   • pipeline (text): Sales process definition to scope the metrics.
   • Output: Performance summaries per representative, including closed volume, revenue totals, and success ratios.

6. hubspot_get_pipeline_analytics

   • Provides deep analysis into the flow and conversion efficiency of a designated sales pipeline.
   • Mandatory Arguments:
   • pipelineId (text): The unique identifier of the sales pipeline structure.
   • period (text): The temporal segment for reporting (e.g., 'quarterly', 'yearly').
   • startDate (text): Start date for data aggregation (ISO format).
   • Optional Arguments:
   • endDate (text): End date for data aggregation (ISO format).
   • Output: Metrics for each stage, such as deal counts, associated value, transition success rates, and average dwell time.

7. hubspot_get_forecast_analytics

   • Projects anticipated future sales results based on current pipeline health and historical trends.
   • Mandatory Argument:
   • period (text): The unit for projecting future results (e.g., 'monthly', 'yearly').
   • Optional Arguments:
   • numberOfPeriods (integer, default: 3): How many future intervals to project.
   • pipeline (text): Sales pathway to base the projection upon.
   • Output: Estimated financial outcomes for upcoming reporting periods.

Initialization Requirements

1. HubSpot Private Application Setup:

2. Navigate to your HubSpot portal settings.

3. Access Integrations, then locate Private Apps.
4. Initiate the creation of a new private application, assigning it a descriptive label.
5. Crucially, configure the necessary API access scopes (see list below).

6. Generate the app and capture the resulting private access token.

7. Necessary Authorization Scopes:

8. crm.objects.contacts.read
9. crm.objects.contacts.write
10. crm.objects.deals.read
11. crm.objects.deals.write
12. crm.objects.companies.read
13. crm.objects.companies.write
14. crm.objects.owners.read
15. crm.objects.quotes.read
16. crm.objects.line_items.read
17. crm.objects.custom.read
18. crm.schemas.deals.read
19. crm.schemas.contacts.read
20. crm.schemas.companies.read
21. crm.schemas.custom.read

Execution via Claude Desktop Client

Incorporate the following configuration fragment into your claude_desktop_config.json file:

Using npx Package Manager

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-hubspot"],
      "env": {
        "HUBSPOT_API_KEY": "your-api-key-here"
      }
    }
  }
}

Using Docker Container

{
  "mcpServers": {
    "hubspot": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "HUBSPOT_API_KEY", "mcp/hubspot"],
      "env": {
        "HUBSPOT_API_KEY": "your-api-key-here"
      }
    }
  }
}

Troubleshooting Guide

If operational faults occur, verify the following system prerequisites:

1. Confirmation that all indispensable API scopes are correctly provisioned on the HubSpot private application.
2. Assurance that the API authentication credential has been accurately transferred to the configuration file.
3. Validation that the utilized HubSpot subscription tier supports access to the specific API endpoints being invoked.

Construction Process

To containerize the server:

docker build -t mcp/hubspot -f Dockerfile .

Licensing Stipulations

This MCP server is distributed under the terms of the MIT License. This permission grants users the liberty to employ, modify, and redistribute the software, contingent upon adherence to the MIT License's conditions. Full particulars are available within the LICENSE file in the source repository.

Contextualization: Business Process Utilities (WIKIPEDIA)

Business administration utilities encompass the collection of mechanisms, software, computational frameworks, and structured approaches utilized by enterprises to successfully navigate shifting market conditions, maintain a competitive foothold, and systematically enhance operational outcomes. These tools span functional areas such as strategic charting, workflow governance, data recording, personnel management, arbitration, oversight, and performance measurement. The modern landscape of management utilities is characterized by rapid transformation, driven by technological acceleration, complicating the selection process for optimal solutions for any given organizational context. This complexity arises from relentless pressure to reduce expenditures while simultaneously maximizing revenue generation, deeply understanding consumer necessities, and ensuring product delivery aligns precisely with client expectations.

Functional Classification:

• Mechanisms for data ingestion and integrity verification across all organizational divisions.
• Frameworks dedicated to monitoring and refining core operational flows.
• Systems designed for data aggregation to facilitate higher-level organizational decision-making.

Managers must adopt a proactive, strategic viewpoint regarding these utilities, rather than passively adopting the newest available technology. Tools must be meticulously vetted and subsequently tailored to fit the specific operational requirements of the entity, reversing the common error of forcing organizational structure around off-the-shelf software.