HubSpot MCP Server Bridge

An advanced implementation of the Model Context Protocol (MCP) gateway, engineered for seamless, bi-directional communication with the HubSpot CRM environment, empowering intelligent digital assistants to interface directly with proprietary organizational data.

System Overview

This dedicated MCP gateway furnishes a complete arsenal of functionalities for engaging with the HubSpot CRM Application Programming Interface (API). This permits AI-driven entities to:

• Provision and govern associated customer and corporate entities within the CRM structure.
• Fetch granular timelines of corporate engagement and historical interaction metrics.
• Query the most recent interaction records spanning the entire HubSpot tenancy.
• Obtain curated lists reflecting recently activated customer and corporate segments.
• Execute critical CRM procedures without diverting control from the conversational AI interface.

Rationale for Adoption

• Effortless AI Synchronization: Establishes a direct conduit between your intelligent systems and the live data reservoir of your HubSpot CRM.
• Streamlined CRM Workflows: Allows routine HubSpot manipulations to be executed through natural, human-like language directives.
• Up-to-the-Second Data Retrieval: Guarantees access to temporally accurate intelligence sourced directly from your HubSpot instance.
• Robust Credential Handling: Leverages HubSpot's established, secure API token authorization mechanisms.
• Modular Architecture: Designed for facile extension to incorporate supplementary HubSpot API features as organizational needs mature.

Deployment Instructions

bash

Acquire the source repository

git clone https://github.com/lkm1developer/hubspot-mcp-server.git cd hubspot-mcp-server

Install required dependencies

npm install

Compile the project binaries

npm run build

Configuration Protocols

The operational service mandates a valid HubSpot API access credential. This token is obtainable via:

1. Navigating to your HubSpot Developer Portal
2. Instituting a private application, specifying the requisite permissions (contacts, companies, engagements).
3. Capturing the resulting authorization token.

The credential can be provisioned via two primary channels:

1. As an environment variable injection:

HUBSPOT_ACCESS_TOKEN=your-secret-token-here

1. As a runtime command-line override:

npm start -- --access-token=your-secret-token-here

For iterative development, establishing a .env file in the repository's root directory is recommended for secret persistence:

HUBSPOT_ACCESS_TOKEN=your-secret-token-here

Operational Execution

Initiating the Gateway Service

bash

Start the standard service instance

npm start

Or initiate with a pre-defined access credential

npm start -- --access-token=your-secret-token-here

Launch the Secure Event Stream (SSE) endpoint with necessary verification

npx mcp-proxy-auth node dist/index.js

Implementing Authorization for the SSE Endpoint

The SSE communication layer incorporates the mcp-proxy-auth utility for credential validation. To activate this security layer:

1. Install the necessary proxy package: bash npm install mcp-proxy-auth

2. Define the AUTH_SERVER_URL environment variable to reference your key validation endpoint: bash export AUTH_SERVER_URL=https://your-verification-service.com/validate

3. Execute the SSE service employing the authorization wrapper: bash npx mcp-proxy-auth node dist/index.js

4. The secure SSE connection point will resolve to:

localhost:8080/sse?apiKey=your-provided-key

Substitute your-provided-key with the actual authentication key expected by your verification service.

The mcp-proxy-auth utility functions as an intermediary proxy that: - Intercepts all incoming transmissions destined for your SSE service. - Validates client credentials against your designated backend authentication service. - Enforces access control, permitting only successfully authenticated traffic to reach the SSE destination.

Integration with Autonomous Assistants

This MCP gateway is architecturally optimized for compatibility with AI assistants natively supporting the Model Context Protocol specification. Upon successful activation, the server dynamically exposes a suite of high-utility functions that authorized AI agents can invoke to manipulate and query data housed within the HubSpot CRM ecosystem.

Accessible Toolset

The gateway makes the following specialized HubSpot integration methods available:

1. hubspot_create_contact
2. Action: Generates a fresh contact record in HubSpot, incorporating logic to detect and prevent data duplication.
3. Required Parameters:
   • firstname (string): The contact's given name.
   • lastname (string): The contact's family name.
4. Optional Parameters:
   • email (string): The contact's electronic mail address.
   • properties (object): A dictionary containing supplementary attributes (e.g., associated organization, telephone number, designation).

5. Illustration:

   { "firstname": "Alex", "lastname": "Smith", "email": "alex.smith@corp.net", "properties": { "company": "Global Dynamics", "phone": "(800) 555-1212", "jobtitle": "Senior Analyst" } }

6. hubspot_create_company

7. Action: Establishes a new corporate entity entry within HubSpot, including duplicate screening mechanisms.
8. Required Parameters:
   • name (string): The designated title of the organization.
9. Optional Parameters:
   • properties (object): Supplementary corporate attributes.

10. Illustration:

    { "name": "Innovate Solutions Ltd", "properties": { "domain": "innovate.co", "industry": "Consulting", "city": "Austin", "state": "TX" } }

11. hubspot_get_company_activity

12. Action: Retrieves the exhaustive log of interaction history pertaining to a specific corporate entity.
13. Required Parameters:
    • company_id (string): The unique internal identifier assigned by HubSpot to the company.

14. Output Detail: Delivers comprehensive engagement records spanning electronic mail correspondence, phone logs, scheduled meetings, internal memos, and assigned action items.

15. hubspot_get_recent_engagements

16. Action: Fetches recent engagement data aggregated from all associated customer and corporate profiles.
17. Optional Parameters:
    • days (number, preset: 7): Defines the temporal lookback window in days.
    • limit (number, preset: 50): Sets the maximum cardinality of engagement records returned.

18. Output Detail: Provides a time-sequenced compilation of all pertinent recent CRM events.

19. hubspot_get_active_companies

20. Action: Queries and returns a list of corporate entities exhibiting the highest levels of recent interaction.
21. Optional Parameters:
    • limit (number, preset: 10): The ceiling on the number of company records to be retrieved.

22. Output Detail: Returns records ordered descendingly based on their last modification timestamp.

23. hubspot_get_active_contacts

24. Action: Queries and returns a list of individual contacts demonstrating the most recent engagement.
25. Optional Parameters:
    • limit (number, preset: 10): The maximum count of contact records to fetch.

26. Output Detail: Returns records ordered descendingly based on their last modification timestamp.

27. hubspot_update_contact

28. Action: Modifies data fields for an existing contact entry in HubSpot (operation is silently skipped if the specified ID is not found).
29. Required Parameters:
    • contact_id (string): The HubSpot-assigned ID of the contact targeted for modification.
    • properties (object): A collection of attribute key/value pairs slated for updating.

30. Illustration:

    { "contact_id": "12345", "properties": { "email": "new.address@firm.net", "phone": "(888) 111-2222", "jobtitle": "Lead Software Architect" } }

31. hubspot_update_company

32. Action: Overwrites data for an existing corporate record within HubSpot (operation is silently ignored if the company ID is absent).
33. Required Parameters:
    • company_id (string): The unique HubSpot identifier for the corporation.
    • properties (object): The specific corporate attributes requiring an update.

34. Illustration:

    { "company_id": "67890", "properties": { "domain": "newdomainname.org", "phone": "(800) 555-1212", "industry": "Data Services", "city": "Seattle", "state": "WA" } }

Extending the Connector Framework

The architecture is inherently modular to facilitate easy augmentation with new HubSpot API functionalities:

1. Introduce novel methods within the HubSpotClient abstraction located in src/hubspot-client.ts.
2. Register these new handling functions within the setupToolHandlers routine in src/index.ts.
3. Recompile the codebase utilizing npm run build.

Project Licensing

This software asset is distributed under the permissive MIT License terms; consult the LICENSE file for comprehensive details.

Indexing Tags

HubSpot, CRM System, Model Context Protocol, MCP Framework, AI Interfacing, TypeScript Development, API Connectivity, HubSpot Ecosystem Access, Customer Data Management, Corporate Record Control, Interaction Monitoring, Intelligent Automation Tools