HubSpot Model Context Protocol Endpoint

Operational Summary

This service acts as a Model Context Protocol (MCP) gateway, specifically designed to bridge large language models with the HubSpot ecosystem. It translates abstract model requests into concrete HubSpot API operations, ensuring data synchronization and operational access through a vendor-agnostic protocol layer.

Refer to Anthropic's MCP specification for foundational protocol details.

Exposed Data Structures (Resources)

The following persistent data streams are available for real-time querying:

• hubspot://hubspot_contacts: Live representation of the contact database.
• hubspot://hubspot_companies: Live representation of the company database.
• hubspot://hubspot_recent_engagements: Chronological log of customer interactions (calls, emails, meetings) recorded within the trailing 72 hours.

Updates within HubSpot trigger automatic propagation across these resource endpoints.

Usage Scenarios (Example Prompts)

• Data Ingestion from Unstructured Text:

  Parse the attached professional summary and materialize corresponding records in HubSpot Contacts and Companies datasets:

  John Doe Software Engineer, Tech Corp SF Bay Area • 500+ Network Connections

  Work History: Tech Corp Software Engineer Commenced Jan 2020 (4 years duration)

  Previous Company Inc. Senior Developer 2018 - 2020 (2 years duration)

  Education: UC Berkeley, Computer Science, BS (2014-2018)

• Pipeline Status Query:

  Provide a summary of the most recent transactional milestones affecting my assigned accounts.

Available Utility Functions (Tools)

The server exposes transactional and retrieval methods for CRM object manipulation:

Contact Operations

• hubspot_get_contacts
• Purpose: Fetches the complete set of tracked contacts.
• Parameters: None.

• Output Schema: List of contact entity payloads.

• hubspot_create_contact

• Purpose: Registers a new contact, incorporating pre-creation validation to prevent duplication.
• Input:
  • firstname (Text): Recipient's given name.
  • lastname (Text): Recipient's surname.
  • email (Text, Optional): Primary electronic mail address.
  • properties (Map, Optional): Key-value pairs for auxiliary fields (e.g., {"phone": "555-1212", "company": "ACME Corp"}).
• Logic:
  • Executes an identity check based on name combination, optionally factoring in company association.
  • If an identical entry exists, the existing record identifier is returned.
  • Creation is contingent upon the absence of a match.

Company Operations

• hubspot_get_companies
• Purpose: Queries the ledger of registered corporate entities.
• Parameters: None.

• Output Schema: List of company entity payloads.

• hubspot_create_company

• Purpose: Registers a new organizational record, with safeguards against redundancy.
• Input:
  • name (Text): Official name of the organization.
  • properties (Map, Optional): Additional metadata (e.g., {"domain": "corp.net", "industry": "Software"}).

• Logic:

  • Compares incoming names against existing entries.
  • Returns existing ID on match; otherwise, initiates record creation.

• hubspot_get_company_activity

• Purpose: Audits the chronological history associated with a specific firm.
• Input:
  • company_id (Identifier): The unique internal identifier assigned by HubSpot.
• Output Schema: List of activity log entries.

Interaction Tracking

• hubspot_get_recent_engagements
• Purpose: Aggregates all documented interactions across the entire client base from the last three days.
• Parameters: None.
• Output Schema: Comprehensive list of engagement objects.

Authentication Strategy (Multi-Tenancy Support)

This server is architected for secure, per-user credential isolation, avoiding reliance on static, global secrets. Authentication requires the client application to supply the specific user's access credential with every invocation via one of the following mechanisms:

1. HTTP Header Injection: X-HubSpot-Access-Token: <USER_TOKEN>
2. Request Payload Field: Inclusion of the accessToken key.
3. Request Payload Field: Inclusion of the hubspotAccessToken key.

This design mandates that the calling system (e.g., your application backend) manages and securely provisions user-specific tokens.

Implementation Blueprint (Client-Side Example)

javascript // Pseudo-code demonstrating token injection for a specific end-user async function invokeHubSpotService(endUserID, requiredOperation, parameters) { // Step 1: Securely fetch the designated user's HubSpot OAuth token const userCredential = await fetchUserTokenStore(endUserID);

// Step 2: Transmit request, embedding the token in the header const endpointURL = 'https://your-mcp-server.vercel.app/'; const response = await fetch(endpointURL, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-HubSpot-Access-Token': userCredential // Token injection point }, body: JSON.stringify({ action: requiredOperation, ...parameters }) });

return await response.json(); }

Deployment and Accessibility

Prerequisites for Operation

Authentication requires valid HubSpot Personal Access Tokens (PATs). Tokens must be generated through the HubSpot developer interface: 1. Navigate to HubSpot Account Settings -> Integrations -> Private Applications. 2. Create a new private application, providing basic metadata. 3. Crucially, define necessary scopes (e.g., crm.objects.contacts.read, crm.objects.companies.write, etc.). 4. Securely retain the generated token; do not expose it in client-side code or public repositories.

Containerization (Docker)

The service is containerized for easy deployment across Linux environments.

Image Acquisition

Pull the pre-built image from Docker Hub: bash docker pull buryhuang/mcp-hubspot:latest

Local Build Procedure

If source compilation is preferred: bash docker build -t enterprise-crm-connector .

To initiate the service using the image: bash docker run -d -p 8080:8080 buryhuang/mcp-hubspot:latest

Multi-Architecture Support

Utilize Docker Buildx for creating manifest sets that cover common processor architectures:

1. Initialize build environment: bash docker buildx create --name multiarchbuilder --use

2. Construct and publish the multi-platform image: 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)

For immediate activation within compatible AI environments:

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

Docker Configuration Snippet for Automated Launch

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

Development Environment Setup

For source code contribution or local testing:

bash pip install -e . # Assuming Python package structure

Legal Notice

This software is distributed under the permissive MIT License.

---

Contextual Note on Business Tooling: Modern enterprise management systems encompass a broad spectrum of digital aids designed to optimize organizational performance against dynamic market pressures. Effective adoption hinges not on adopting the newest technology, but on the strategic alignment and customization of chosen tools (like CRM systems) to intrinsic corporate processes. Failure to adapt tools often leads to operational instability, regardless of the software's inherent capability.