home / mcp / hubspot mcp server

HubSpot MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with HubSpot CRM data, providing built-in vector storage and caching mechanisms help overcome HubSpot API limitations while improving response times.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

You can use the HubSpot MCP Server to let AI assistants interact with your HubSpot CRM data directly. It provides seamless access to contacts, companies, and engagement data, with built-in vector storage and caching to improve relevance and speed during complex CRM workflows.

How to use

Connect your MCP client to the HubSpot MCP Server to enable AI-assisted CRM operations. Start the server container with your HubSpot access token and an optional persistent storage directory. Then, in your MCP client, reference the hubspot MCP server as a data source and issue high-value HubSpot actions such as creating contacts or retrieving recent activity. The server’s semantic search and thread-level indexing help you retrieve context from past conversations and interactions for richer responses.

How to install

Prerequisites You need Docker installed on your machine to run the HubSpot MCP Server container.

Option A: Run the server via Docker (recommended)

# Run the HubSpot MCP Server container
# Replace your_token with your actual HubSpot access token
# Optional: replace /path/to/storage with your desired persistent storage path

docker run -i --rm \
  -e HUBSPOT_ACCESS_TOKEN=your_token \
  -v /path/to/storage:/storage \
  buryhuang/mcp-hubspot:latest

Option B: Build and run locally (advanced)

# Clone the project
git clone https://github.com/buryhuang/mcp-hubspot.git
cd mcp-hubspot

# Build the Docker image locally (if you prefer to build from source)
docker build -t mcp-hubspot .

# Run the built image with your token and optional storage
# Replace your_token with your actual HubSpot access token
# Optional: replace /path/to/storage with your desired persistent storage path

docker run -i --rm \
  -e HUBSPOT_ACCESS_TOKEN=your_token \
  -v /path/to/storage:/storage \
  mcp-hubspot:latest

Configuration notes

When you run the server, supply your HubSpot access token with the required scopes: crm.objects.contacts (read/write), crm.objects.companies (read/write), and sales-email-read. You can also specify a storage directory to persist data between sessions via the /storage mount point in the container.

Available tools

hubspot_create_contact

Create contacts in HubSpot with duplicate prevention to avoid creating multiple entries for the same person.

hubspot_create_company

Create companies in HubSpot with duplicate prevention to maintain clean company records.

hubspot_get_company_activity

Retrieve activity data for a specific set of companies to review recent interactions.

hubspot_get_active_companies

Fetch the most recently active companies to focus on current engagement.

hubspot_get_active_contacts

Fetch the most recently active contacts to prioritize outreach.

hubspot_get_recent_conversations

Retrieve recent conversation threads with messages for context.

hubspot_search_data

Perform semantic search across previously retrieved HubSpot data to locate relevant records.