HubSpot MCP server

This MCP server provides integration with HubSpot CRM, allowing AI models to interact with HubSpot data and operations through a standardized interface. It enables tasks like managing contacts and companies, checking recent engagements, and automating workflows through the Model Context Protocol framework.

Installation

Prerequisites

You need a HubSpot access token for each user. To obtain this:

1. Create a private app in your HubSpot account:
   • Go to your HubSpot account settings
   • Navigate to Integrations > Private Apps
   • Click "Create private app"
   • Fill in the basic information (name, description, logo)
   • Define required scopes:
     • oauth (required)
   • Optional scopes:
     • crm.dealsplits.read_write
     • crm.objects.companies.read
     • crm.objects.companies.write
     • crm.objects.contacts.read
     • crm.objects.contacts.write
     • crm.objects.deals.read
   • Review and create the app
   • Copy the generated access token

Keep your access token secure and never commit it to version control.

Docker Installation

You can either pull the image from Docker Hub or build it locally.

Supported Platforms

• Linux/amd64
• Linux/arm64
• Linux/arm/v7

Option 1: Pull from Docker Hub

docker pull buryhuang/mcp-hubspot:latest

Option 2: Build Locally

docker build -t mcp-hubspot .

Running the Container

docker run buryhuang/mcp-hubspot:latest

Installing via Smithery for Claude Desktop

For automatic installation with Smithery:

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

Usage

Multi-User Support

This MCP server works with multiple HubSpot users, each with their own access token. Include the user's access token in each request using one of these methods:

1. In the request header: X-HubSpot-Access-Token: your-token-here
2. In the request body as accessToken: {"accessToken": "your-token-here"}
3. In the request body as hubspotAccessToken: {"hubspotAccessToken": "your-token-here"}

Example Multi-User Integration

async function makeHubSpotRequest(userId, action, params) {
  // Retrieve the user's HubSpot token from your database
  const userToken = await getUserHubSpotToken(userId); 

  // Make request to MCP server with the user's token
  const response = await fetch('https://your-mcp-server.vercel.app/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-HubSpot-Access-Token': userToken
    },
    body: JSON.stringify({
      action,
      ...params
    })
  });
  
  return await response.json();
}

Using with Claude Desktop

Configure your Claude Desktop settings with:

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

Available Resources and Tools

Resources

The server provides access to:

• hubspot://hubspot_contacts: Access to HubSpot contacts
• hubspot://hubspot_companies: Access to HubSpot companies
• hubspot://hubspot_recent_engagements: Access to HubSpot engagements from the last 3 days

All resources automatically update when objects are modified in HubSpot.

Contact Management Tools

• hubspot_get_contacts

  • Retrieves contacts from HubSpot
  • No input required
  • Returns array of contact objects

• hubspot_create_contact

  • Creates a new contact in HubSpot (checks for duplicates)
  • Input:
    • firstname (string): Contact's first name
    • lastname (string): Contact's last name
    • email (string, optional): Contact's email address
    • properties (dict, optional): Additional properties (e.g., {"phone": "123456789", "company": "HubSpot"})

Company Management Tools

• hubspot_get_companies

  • Retrieves companies from HubSpot
  • No input required
  • Returns array of company objects

• hubspot_create_company

  • Creates a new company in HubSpot (checks for duplicates)
  • Input:
    • name (string): Company name
    • properties (dict, optional): Additional properties (e.g., {"domain": "example.com", "industry": "Technology"})

• hubspot_get_company_activity

  • Gets activity history for a specific company
  • Input:
    • company_id (string): HubSpot company ID
  • Returns array of activity objects

Engagement Tools

• hubspot_get_recent_engagements
  • Gets HubSpot engagements from all companies and contacts from the last 3 days
  • No input required
  • Returns array of engagement objects with full metadata

Example Prompts

Creating Contacts from LinkedIn Profiles

Create HubSpot contacts and companies from following:

John Doe
Software Engineer at Tech Corp
San Francisco Bay Area • 500+ connections

Experience
Tech Corp
Software Engineer
Jan 2020 - Present · 4 yrs
San Francisco, California

Previous Company Inc.
Senior Developer
2018 - 2020 · 2 yrs

Education
University of California, Berkeley
Computer Science, BS
2014 - 2018

Checking Recent Activities

What's happening latestly with my pipeline?

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "hubspot" '{"command":"docker","args":["run","-i","--rm","buryhuang/mcp-hubspot:latest"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect