HubSpot MCP Server

What is HubSpot MCP Server about?

Enables AI assistants to interact directly with HubSpot contacts, companies, and engagement data. It adds semantic search via FAISS and caches embeddings, reducing the number of API calls needed and speeding up responses.

How to use HubSpot MCP Server?

1. Obtain a HubSpot access token with the required scopes (crm.objects.contacts, crm.objects.companies, sales-email-read).
2. Deploy the server, preferably with Docker or via the Smithery CLI:

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

   Set the environment variable HUBSPOT_ACCESS_TOKEN when starting the container.
3. Configure your AI assistant (e.g., Claude) to call the MCP tools exposed by the server.

Key features of HubSpot MCP Server

• Direct CRM operations: create contacts/companies with duplicate prevention, fetch recent activity, retrieve conversations.
• Semantic search: FAISS index stores each conversation thread, allowing vector‑based queries across previously retrieved data.
• Embedding caching: Uses SentenceTransformer with automatic caching to avoid redundant embedding calculations.
• Persistent storage: Optionally mount a host directory to keep vectors and caches between sessions.
• Zero‑config Docker images: Multi‑architecture images ready for amd64 and arm64.

Use cases of HubSpot MCP Server

• Automating lead enrichment by parsing LinkedIn profiles and creating corresponding HubSpot records.
• Generating real‑time pipeline summaries for sales teams via natural‑language queries.
• Building AI‑driven chatbots that can look up recent conversation threads and suggest next actions.
• Enhancing AI assistants with semantic memory of past CRM interactions for more contextual responses.

FAQ from the HubSpot MCP Server

Q: Which environment variable supplies the HubSpot token?
A: HUBSPOT_ACCESS_TOKEN.

Q: Do I need to run a separate vector database?
A: No, FAISS runs in‑process and persists to the configured storage directory.

Q: How can I keep data between container restarts?
A: Mount a host directory to /storage (e.g., -v /my/data:/storage).

Q: What client libraries are supported?
A: Any AI model that can call MCP tools, such as Anthropic Claude, OpenAI, etc.

Q: Can I limit the number of API calls to HubSpot?
A: Yes, the built‑in caching and vector storage reduce repeated fetches.

HubSpot MCP Server

Overview

A Model Context Protocol (MCP) server that enables AI assistants to interact with HubSpot CRM data. This server bridges AI models with your HubSpot account, providing direct access to contacts, companies, and engagement data. Built-in vector storage and caching mechanisms help overcome HubSpot API limitations while improving response times.

Our implementation prioritizes the most frequently used, high-value HubSpot operations with robust error handling and API stability. Each component is optimized for AI-friendly interactions, ensuring reliable performance even during complex, multi-step CRM workflows.

Why MCP-HubSpot?

• Direct CRM Access: Connect Claude and other AI assistants to your HubSpot data without intermediary steps
• Context Retention: Vector storage with FAISS enables semantic search across previous interactions
• Zero Configuration: Simple Docker deployment with minimal setup

Example Prompts

Create HubSpot contacts and companies from this LinkedIn profile:
[Paste LinkedIn profile text]

What's happening lately with my pipeline?

Available Tools

The server offers tools for HubSpot management and data retrieval:

Tool	Purpose
hubspot_create_contact	Create contacts with duplicate prevention
hubspot_create_company	Create companies with duplicate prevention
hubspot_get_company_activity	Retrieve activity for specific companies
hubspot_get_active_companies	Retrieve most recently active companies
hubspot_get_active_contacts	Retrieve most recently active contacts
hubspot_get_recent_conversations	Retrieve recent conversation threads with messages
hubspot_search_data	Semantic search across previously retrieved HubSpot data

Performance Features

• Vector Storage: Utilizes FAISS for efficient semantic search and retrieval
• Thread-Level Indexing: Stores each conversation thread individually for precise retrieval
• Embedding Caching: Uses SentenceTransformer with automatic caching
• Persistent Storage: Data persists between sessions in configurable storage directory
• Multi-platform Support: Optimized Docker images for various architectures

Setup

Prerequisites

You'll need a HubSpot access token with these scopes:

• crm.objects.contacts (read/write)
• crm.objects.companies (read/write)
• sales-email-read

Quick Start

# Install via Smithery (recommended)
npx -y @smithery/cli@latest install mcp-hubspot --client claude

# Or pull Docker image directly
docker run -e HUBSPOT_ACCESS_TOKEN=your_token buryhuang/mcp-hubspot:latest

Docker Configuration

For manual configuration in Claude desktop:

{
  "mcpServers": {
    "hubspot": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "HUBSPOT_ACCESS_TOKEN=your_token",
        "-v", "/path/to/storage:/storage",  # Optional persistent storage
        "buryhuang/mcp-hubspot:latest"
      ]
    }
  }
}

Building Docker Image

To build the Docker image locally:

git clone https://github.com/buryhuang/mcp-hubspot.git
cd mcp-hubspot
docker build -t mcp-hubspot .

For multi-platform builds:

docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 -t buryhuang/mcp-hubspot:latest --push .

Development

pip install -e .

License

MIT License