HubSpot CRM Integration Module

Module Synopsis

This implementation adheres to the Model Context Protocol (MCP) specification, serving as an external service layer to facilitate secure and structured interaction with HubSpot's ecosystem. It standardizes data access patterns for generative models interacting with CRM assets.

Refer to Anthropic's MCP specification for protocol details.

Exposed Data Streams (Resources)

The following dynamically updating data endpoints are exposed. Modifications in HubSpot trigger automatic refreshes for these resources:

• hubspot://hubspot_contacts: Provides granular access to the organization's contact database.
• hubspot://hubspot_companies: Grants visibility into registered business entities/organizations.
• hubspot://hubspot_recent_engagements: Delivers a curated feed of interactions (calls, emails, meetings) logged within the preceding 72 hours.

Operational Examples

• Data Ingestion from Unstructured Sources:

  Process the following professional summary and instantiate corresponding records within HubSpot CRM:

  John Doe Software Engineer @ Tech Corp San Francisco Bay Area | Seniority Level: 500+ Network Connections

  Career History: Tech Corp: Software Engineer (Commenced Jan 2020, Ongoing) Previous Company Inc.: Senior Developer (2018 to 2020)

  Academic Background: UC Berkeley: B.S. in Computer Science (2014-2018)

• Pipeline Status Query:

  Query the current status and recent transactional history pertaining to my established sales pipeline.

API Functions (Tools)

The module provides specialized methods for data manipulation within HubSpot:

Contact Manipulation

• hubspot_get_contacts
• Fetches the current roster of CRM contacts.
• Parameters: None.

• Output: A serialized array of contact entity records.

• hubspot_create_contact

• Attempts to provision a new contact record, incorporating built-in duplicate detection logic.
• Input Schema:
  • firstname (string): Recipient's given name.
  • lastname (string): Recipient's family name.
  • email (string, optional): Electronic mail address.
  • properties (object, optional): Supplementary attributes map.
  • E.g., {"phone": "123456789", "company": "HubSpot"}
• Execution Logic:
  • Performs a lookup based on name matching (first and last).
  • If company is specified in properties, company name matching is included in the deduplication check.
  • If a high-confidence match is identified, the existing entity details are returned.
  • Creation proceeds only if no record satisfies the match criteria.

Organization Management

• hubspot_get_companies
• Retrieves a list of all entities registered as companies.
• Parameters: None.

• Output: Array of company objects.

• hubspot_create_company

• Registers a new organization entry, avoiding duplication.
• Input Schema:
  • name (string): Official name of the organization.
  • properties (object, optional): Additional organizational metadata.
  • E.g., {"domain": "example.com", "industry": "Technology"}

• Execution Logic:

  • Identifies potential duplicates based on the provided company name.
  • If a match is confirmed, the existing object ID is returned.
  • A new entry is persisted only upon verification of uniqueness.

• hubspot_get_company_activity

• Accesses the chronological log of interactions tied to a specific organization.
• Input:
  • company_id (string): The unique identifier assigned by HubSpot for the company entity.
• Output: An array detailing all associated activity events.

Interaction Tracking

• hubspot_get_recent_engagements
• Fetches interaction data across all associated contacts and companies recorded over the last 72 hours.
• Parameters: None.
• Output: Comprehensive array of engagement records.

Multi-Tenancy and Authentication Strategy

This service deployment is engineered for secure operation across disparate HubSpot user contexts. It consciously avoids reliance on static, global credentials. Authentication must be supplied dynamically per invocation.

User-specific HubSpot authorization tokens must be supplied with each request via one of the following secure channels:

1. HTTP Header Injection: X-HubSpot-Access-Token: [secure_token_value]
2. JSON Request Payload: Inclusion of the accessToken field.
3. JSON Request Payload: Inclusion of the hubspotAccessToken field.

This structure facilitates token management within your intermediary application layer (e.g., a database like Supabase).

Multi-User Workflow Illustration

javascript // Schema for invoking the HubSpot MCP endpoint in a partitioned environment async function invokeHubSpotService(tenantIdentifier, operationalCommand, parameters) { // Securely fetch the specific user's credential const userAuthToken = await retrieveTenantToken(tenantIdentifier);

// Transmit request, embedding the requisite authentication header const apiResponse = await fetch('https://your-mcp-server.vercel.app/', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-HubSpot-Access-Token': userAuthToken }, body: JSON.stringify({ action: operationalCommand, ...parameters }) });

return await apiResponse.json(); }

Deployment Guide

Prerequisites

A valid HubSpot API access credential is required for every user context intended to interface with this system. These are generated via HubSpot Private Applications: 1. Navigate to your HubSpot account settings dashboard. 2. Locate the 'Integrations' section, then 'Private Apps'. 3. Initiate a new private application setup. 4. Mandatory Scopes: Ensure the oauth scope is enabled. 5. Recommended CRM Scopes: Grant read/write access for crm.objects.companies and crm.objects.contacts. 6. Securely store the generated token; it must never be exposed in source code repositories.

Containerization (Docker)

The image is pre-built for major Linux architectures.

Retrieval

bash docker pull buryhuang/mcp-hubspot:latest

Local Image Compilation

bash docker build -t crm-hub-connector .

To initiate the service: bash docker run -i --rm buryhuang/mcp-hubspot:latest

Multi-Architecture Image Construction

Leverage docker buildx for publishing images compatible across various hardware platforms (e.g., Intel/ARM).

1. Builder Initialization: bash docker buildx create --use

2. Build and Push Command: bash docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t buryhuang/mcp-hubspot:latest --push .

3. Verification: bash docker buildx imagetools inspect buryhuang/mcp-hubspot:latest

Integration with Claude Desktop (Smithery)

Installation via the Smithery CLI utility:

bash npx -y @smithery/cli@latest install mcp-hubspot --client claude

Docker Configuration Snippet

For direct client configuration:

{ "mcpServers": { "hubspot_crm": { "command": "docker", "args": [ "run", "-i", "--rm", "buryhuang/mcp-hubspot:latest" ] } } }

Development Setup

To establish the local development environment:

bash pip install -e .

Project Licensing

Distributed under the terms of the MIT License.

---

Supplemental Context: Cloud Computing Foundation

Cloud infrastructure is fundamentally defined by the ability to provide elastic, metered, and on-demand computational resources via a network fabric. The foundational principles, as codified by NIST, emphasize rapid scalability and broad accessibility across diverse end-user apparatuses.