HubSpot MCP server

This HubSpot MCP server provides integration with HubSpot CRM, allowing AI models to interact with HubSpot data and operations through the standardized Model Context Protocol (MCP). It enables access to contacts, companies, and recent engagements, with tools to create and manage HubSpot objects.

Installation

Prerequisites

Before installing, you'll need a HubSpot access token for each user:

1. Create a private app in your HubSpot account:
   • Go to your HubSpot account settings
   • Navigate to Integrations > Private Apps
   • Click "Create private app"
   • Provide 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

Docker Installation

The server can be installed using Docker with two options:

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

To install automatically via Smithery:

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

Usage

Multi-User Support

The server supports multiple HubSpot users with individual access tokens. Include the access token with each request using one of these methods:

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

Integration Example

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();
}

Configure with Claude Desktop

Add this configuration to your Claude Desktop setup:

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

Available Resources

The server provides access to these HubSpot resources:

• 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 changes occur in HubSpot.

Available Tools

Contact Management

Retrieve Contacts

hubspot_get_contacts

Retrieves all contacts from HubSpot. No input required.

Create Contact

hubspot_create_contact

Creates a new contact (checks for duplicates first)

Required parameters:

• firstname: Contact's first name
• lastname: Contact's last name

Optional parameters:

• email: Contact's email address
• properties: Additional contact properties as a dictionary
  • Example: {"phone": "123456789", "company": "HubSpot"}

Company Management

Retrieve Companies

hubspot_get_companies

Retrieves all companies from HubSpot. No input required.

Create Company

hubspot_create_company

Creates a new company (checks for duplicates first)

Required parameters:

• name: Company name

Optional parameters:

• properties: Additional company properties as a dictionary
  • Example: {"domain": "example.com", "industry": "Technology"}

Get Company Activity

hubspot_get_company_activity

Retrieves activity history for a specific company

Required parameters:

• company_id: HubSpot company ID

Engagement Management

Retrieve Recent Engagements

hubspot_get_recent_engagements

Gets HubSpot engagements from all companies and contacts from the last 3 days. No input required.

Example Prompts

Creating Contacts from LinkedIn

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 Pipeline Status

What's happening latestly with my pipeline?

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.