HubSpot

What is mcp-hubspot?

mcp-hubspot is a Model Context Protocol (MCP) server that enables AI assistants, such as Claude, to interact directly with HubSpot CRM data. It acts as a bridge between AI models and your HubSpot account, providing access to contacts, companies, and engagement data. The server incorporates built-in vector storage (using FAISS) and caching mechanisms to overcome HubSpot API limitations and improve response times.

How to use mcp-hubspot?

mcp-hubspot can be easily deployed via Docker. You can install it using Smithery CLI (recommended) with npx -y @smithery/cli@latest install mcp-hubspot --client claude or pull the Docker image directly using docker run -e HUBSPOT_ACCESS_TOKEN=your_token buryhuang/mcp-hubspot:latest. For manual configuration in Claude desktop, a JSON snippet is provided for mcpServers configuration. Building the Docker image locally is also an option.

Key Features of mcp-hubspot

• Direct CRM Access: Connects AI assistants like Claude directly to HubSpot data.
• Context Retention: Utilizes FAISS for vector storage, enabling semantic search across past interactions.
• Zero Configuration: Simple Docker deployment for quick setup.
• Optimized Operations: Prioritizes frequently used HubSpot operations with robust error handling.
• Available Tools: Provides tools for HubSpot management and data retrieval, including hubspot_create_contact, hubspot_create_company, hubspot_get_company_activity, hubspot_get_active_companies, hubspot_get_active_contacts, hubspot_get_recent_conversations, and hubspot_search_data.
• Performance Features: Includes vector storage (FAISS), thread-level indexing, embedding caching (SentenceTransformer), persistent storage, and multi-platform Docker image support.

Use Cases of mcp-hubspot

• Automated CRM Data Management: Create HubSpot contacts and companies from external data sources (e.g., LinkedIn profiles) using AI prompts.
• Pipeline Monitoring: Ask AI assistants for updates on your sales pipeline.
• Semantic Search: Perform semantic searches across previously retrieved HubSpot data to quickly find relevant information.
• Enhanced AI Interactions: Enable AI models to perform complex, multi-step CRM workflows efficiently and reliably.

FAQ from mcp-hubspot

• What HubSpot scopes are required? You need crm.objects.contacts (read/write), crm.objects.companies (read/write), and sales-email-read scopes for your HubSpot access token.
• How does it handle duplicate prevention? The hubspot_create_contact and hubspot_create_company tools include duplicate prevention mechanisms.
• Can data persist between sessions? Yes, data can persist between sessions by configuring a persistent storage directory using the -v flag in the Docker run command.
• What is FAISS used for? FAISS is used for efficient semantic search and retrieval of data, enabling context retention across interactions.

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