HubSpot Interaction Module for Model Context Protocol (MCP)

This dedicated MCP server facilitates secure and structured communication between the LLM context and the HubSpot API for advanced sales data analysis and record management.

Important Declaration

This module is an independently developed, open-source utility. It is neither officially sponsored, affiliated, nor sanctioned by HubSpot, Inc. Its functionality relies solely on interacting with publicly available HubSpot APIs.

Available Service Endpoints

Primary Data Manipulation Tools (CRM Objects)

1. hubspot_search_contacts

2. Executes a lookup operation against the contact database based on a provided textual criterion.

3. Mandatory Parameter:
   • query (String): The search string (e.g., constituent's email address, full name).
4. Optional Parameters:
   • count (Number, Default: 10): Specifies the upper bound on the number of contact records to be returned.
   • propertyList (Array): A specification of which object attributes (properties) should be included in the output.

5. Output: A collection of matching contact records, populated with the requested attribute values.

6. hubspot_get_contact

7. Retrieves the complete profile details for a single contact identified by its unique identifier.

8. Mandatory Parameter:
   • contactId (String): The immutable identifier of the target contact.
9. Optional Parameters:
   • properties (Array): A subset of attributes to be fetched.

10. Output: The full data structure for the specified contact.

11. hubspot_create_contact

12. Provision a new contact entity within the HubSpot ecosystem.

13. Mandatory Parameter:
    • properties (Object): A dictionary containing the necessary attributes, crucially including the email field.

14. Output: The system confirmation and details of the newly instantiated contact record.

15. hubspot_update_contact

16. Modifies the attributes of an existing contact record.

17. Mandatory Parameters:
    • contactId (String): The identifier of the contact to be altered.
    • properties (Object): The key-value pairs representing the attributes requiring revision.

18. Output: A confirmation receipt indicating the successful modification.

19. hubspot_list_deals

20. Fetches a paginated listing of all sales opportunity records.

21. Optional Parameters:
    • limit (Number, Default: 10, Max: 100): Controls the size of the returned batch.
    • after (String): A cursor token utilized for navigating to the subsequent segment of the dataset.
    • properties (Array): Specifies which deal attributes should accompany each listing.

22. Output: A sequenced array of deal records and associated metadata.

23. hubspot_get_deal

24. Retrieves the detailed attributes for an individual sales opportunity.

25. Mandatory Parameter:
    • dealId (String): The unique identifier for the sales opportunity.
26. Optional Parameters:
    • properties (Array): A precise list of data fields to be returned.

27. Output: The comprehensive attribute set for the designated deal.

28. hubspot_create_deal

29. Registers a novel sales opportunity into the system.

30. Mandatory Parameter:
    • properties (Object): The initial attribute set for the deal, requiring at minimum the dealname attribute.

31. Output: The system response detailing the newly established deal.

32. hubspot_update_deal

33. Applies modifications to the state or data associated with an extant deal.

34. Mandatory Parameters:
    • dealId (String): The identifier of the opportunity to be updated.
    • properties (Object): The specific attribute changes to implement.

35. Output: A confirmation message verifying the update operation.

36. hubspot_list_companies

37. Provides a segmented enumeration of all corporate records.

38. Optional Parameters:
    • limit (Number, Default: 10, Max: 100): The maximum number of company entries per response.
    • after (String): Pagination pointer for accessing subsequent records.
    • properties (Array): Attributes to include for each listed company.

39. Output: A collection of company records with their specified attributes.

40. hubspot_get_company

    • Retrieves the full profile for a singular corporate entity.
    • Mandatory Parameter:
    • companyId (String): The system ID of the organization.
    • Optional Parameters:
    • properties (Array): The specific data points to retrieve.
    • Output: The complete data payload for the queried company.

Performance and Activity Analysis Tools

1. hubspot_get_sales_analytics

   • Aggregates key sales performance indicators across a defined temporal segment.
   • Mandatory Parameters:
   • period (String): The granularity for aggregation (e.g., daily, weekly, monthly, quarterly, yearly).
   • startDate (String): The initial boundary date for the analysis, formatted as YYYY-MM-DD.
   • Optional Parameters:
   • endDate (String): The terminal boundary date (ISO format).
   • pipeline (String): Identifier for filtering data to a specific sales process.
   • dealStage (String): Filter by a particular stage within the process.
   • dealOwner (String): Filter results to a specific sales representative.
   • Output: Statistical summaries of sales activity segmented by the specified time interval.

2. hubspot_get_deal_history

   • Audits the entire chronological log of modifications applied to a specific transaction.
   • Mandatory Parameter:
   • dealId (String): The target opportunity identifier.
   • Output: A sequenced list detailing every alteration, including timestamps and property changes.

3. hubspot_get_deal_notes

   • Fetches unstructured text annotations linked to a particular sales opportunity.
   • Mandatory Parameter:
   • dealId (String): The identifier of the associated deal.
   • Optional Parameters:
   • limit (Number, Default: 20): Maximum count of notes returned.
   • after (String): Cursor for fetching subsequent note batches.
   • Output: A list of notes, including creation timestamps and textual content.

4. hubspot_get_engagements_by_deal

   • Retrieves all recorded interactions (activities) connected to a given deal record.
   • Mandatory Parameter:
   • dealId (String): The identifier of the sales opportunity.
   • Optional Parameters:
   • types (Array): Filter results to specific interaction types (CALL, EMAIL, MEETING, TASK, NOTE).
   • limit (Number, Default: 20): Maximum number of activities to fetch.
   • after (String): Pagination marker for retrieving older activities.
   • Output: A collection of engagement objects detailing interaction type and content.

5. hubspot_get_sales_performance

   • Calculates key performance indicators (KPIs) for sales personnel over a designated timeframe.
   • Mandatory Parameters:
   • period (String): Defines the measurement interval (daily, weekly, monthly, etc.).
   • startDate (String): The beginning date for performance measurement (YYYY-MM-DD).
   • Optional Parameters:
   • endDate (String): The concluding date for measurement.
   • ownerIds (Array): Restrict analysis to specific sales representatives.
   • pipeline (String): Filter metrics based on a specific sales process.
   • Output: Comprehensive performance statistics per representative, encompassing deal volumes, generated revenue, and success rates.

6. hubspot_get_pipeline_analytics

   • Generates conversion and velocity metrics across the stages of a specified sales pipeline.
   • Mandatory Parameters:
   • pipelineId (String): The unique identifier of the pipeline under review.
   • period (String): The temporal resolution for aggregation (daily, weekly, etc.).
   • startDate (String): The initial date for the analytical window (YYYY-MM-DD).
   • Optional Parameters:
   • endDate (String): The final date for the analytical window.
   • Output: Detailed metrics per pipeline stage, including opportunity counts, associated value, transition success rates, and average time spent in stage.

7. hubspot_get_forecast_analytics

   • Projects future revenue based on current pipeline composition and historical conversion tendencies.
   • Mandatory Parameter:
   • period (String): The projection interval (monthly, quarterly, yearly).
   • Optional Parameters:
   • numberOfPeriods (Number, Default: 3): How many future intervals should be projected.
   • pipeline (String): Optional filter to focus the forecast on one pipeline.
   • Output: Projected sales figures for upcoming reporting periods, extrapolated from existing data trends.

Initial Configuration Requirements

To establish connectivity, a HubSpot Private Application must be generated:

1. Navigate to HubSpot Settings: Access Settings → Account Setup → Integrations → Private Apps.
2. App Creation: Initiate a new private application, assign a descriptive label, and grant the necessary permissions (scopes).

3. Token Acquisition: Upon creation, secure and store the generated Private App Token.

4. Necessary Access Permissions (Scopes):

5. crm.objects.contacts.read, crm.objects.contacts.write
6. crm.objects.deals.read, crm.objects.deals.write
7. crm.objects.companies.read, crm.objects.companies.write
8. crm.objects.owners.read
9. crm.objects.quotes.read
10. crm.objects.line_items.read
11. crm.objects.custom.read
12. Schema Read Permissions for CRM entities: crm.schemas.deals.read, crm.schemas.contacts.read, crm.schemas.companies.read, crm.schemas.custom.read

Integration Instructions for Claude Desktop Environment

In your configuration file (claude_desktop_config.json), utilize one of the following execution methods under the mcpServers block:

Execution via npx (Node Package Executive)

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

Execution via docker Container

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

Troubleshooting Guidelines

If operational issues arise, cross-check the following prerequisites:

1. Confirm all requisite API scopes are active on your HubSpot private application.
2. Ensure the copied API authentication key is accurately situated in the configuration file.
3. Verify that your current HubSpot subscription tier permits usage of the specific API endpoints being targeted.

Building the Container Image

To locally construct the Docker image:

bash docker build -t mcp/hubspot -f Dockerfile .

Licensing Information

This HubSpot MCP implementation is distributed under the terms of the MIT License. Users retain the freedom to employ, alter, and redistribute this software, contingent upon adherence to the stipulated conditions outlined in the MIT License documentation (refer to the LICENSE file in the source repository).

Background Context: XMLHttpRequest (WIKIPEDIA)

XMLHttpRequest (XHR) is a foundational JavaScript Application Programming Interface, structured as a programmatic object, designed to facilitate the transmission of asynchronous HyperText Transfer Protocol (HTTP) requests from a client-side web browser to a remote web server. This mechanism permits web-based applications to dynamically fetch or submit data post-page load without necessitating a full page refresh, forming the backbone of Asynchronous JavaScript and XML (Ajax) development. Before XHR standardized this capability, server interaction relied predominantly on traditional hyperlink navigation or HTML form submissions, which inherently resulted in the reloading of the entire browser view.

== Historical Development == The core concept underlying XHR was first conceptualized around the year 2000 by engineering teams working on Microsoft Outlook. This idea was subsequently realized and integrated into the Internet Explorer 5 browser release (1999). Curiously, the initial implementation did not utilize the standardized XMLHttpRequest identifier. Instead, proprietary COM object instantiations such as ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP") were employed. By the release of Internet Explorer 7 (2006), support for the universally recognized XMLHttpRequest identifier became standard across the platform.

The XMLHttpRequest identifier has since become the established convention across all major browser rendering engines, including Mozilla's Gecko (since 2002), Apple's Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Trajectory === The World Wide Web Consortium (W3C) released an initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. This was followed by a Level 2 specification Working Draft on February 25, 2008, which introduced capabilities for monitoring transfer progress, enabling cross-origin communication, and handling binary data streams. By the close of 2011, the features defined in the Level 2 specification were merged back into the primary specification document. Following developments in late 2012, the responsibility for maintaining and evolving the specification transitioned to the WHATWG, which now manages the document using Web IDL definitions.

== Operational Workflow == Generally, executing an HTTP request utilizing XMLHttpRequest involves a prescribed sequence of programming actions.

1. Instantiate an XMLHttpRequest object via its constructor.
2. Invoke the open() method to define the request method (GET, POST, etc.), specify the target Uniform Resource Identifier (URI), and designate whether the operation should be synchronous or asynchronous.
3. If employing an asynchronous execution model, assign a callback function (event listener) designed to react upon changes in the request's lifecycle state.
4. Initiate the request transmission by calling the send() method, optionally supplying request body data.
5. Monitor the state changes within the designated event listener. Upon successful completion of the server interaction, the object transitions to state 4, termed the "done" state, with the response data typically residing in the responseText property. Beyond these fundamental steps, XHR offers extensive options for request control and response processing. Custom HTTP headers can be injected to guide server behavior, and payload data can be uploaded directly within the send() argument. The received data stream can be parsed immediately into a native JavaScript object structure (e.g., from JSON), or processed incrementally as it arrives, avoiding latency associated with full buffer completion. Furthermore, requests can be manually terminated prematurely or configured with a timeout threshold.