HubSpot MCP Server

How to use

You connect to the HubSpot MCP server from your MCP client and then use the available tools to manage CRM data. You can run the server locally or connect to a remote MCP host. Start by configuring one or more MCP server entries in your client, then perform actions such as listing objects, creating or updating companies and contacts, or managing associations and engagements.

How to install

Prerequisites: Node.js and npm or pnpm, plus access to HubSpot to obtain an access token.

Option 1: NPX Local Install (start quickly without installing globally) Use this snippet in your MCP client config to run the server with NPX.

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": [
        "@shinzolabs/hubspot-mcp"
      ],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "your-access-token-here"
      }
    }
  }
}

Option 2: Build from source (if you want to run from the repository code) Use this snippet in your MCP client config to run the server from a local source build.

{
  "mcpServers": {
    "hubspot": {
      "command": "node",
      "args": [
        "/path/to/hubspot-mcp/index.js"
      ],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "your-access-token-here"
      }
    }
  }
}

Configuration and prerequisites

Configure the access token for HubSpot in the HUBSPOT_ACCESS_TOKEN environment variable. The server uses this token to authenticate requests to HubSpot. You may also set the port for the transport method if you choose a non-default port.

Example environment variable to set in your runtime environment.

export HUBSPOT_ACCESS_TOKEN=your-access-token-here

Supported tools and operations

The HubSpot MCP exposes a comprehensive set of operations for CRM data and engagements. Core operations cover listing, retrieving, creating, updating, and deleting CRM objects; search and batch operations; and management of companies, contacts, leads, and engagements. You can also manage CRM associations and communications preferences, as well as product records.

Security and best practices

Keep your HUBSPOT_ACCESS_TOKEN secure. Do not commit tokens to source control. Use environment variables or secret stores in production. If you rotate tokens, update the environment values accordingly and restart the MCP server.

Troubleshooting

If you encounter authentication or permission errors, verify that the HUBSPOT_ACCESS_TOKEN is valid and has the necessary scopes for the HubSpot API. Ensure network access to HubSpot endpoints from the MCP host and confirm that the token is correctly exposed to the running process.

Notes

Two common ways to run the HubSpot MCP server are via NPX for quick local testing or by building from source for a custom setup. In both cases, you provide your HubSpot access token and, if needed, adjust the port for connectivity.

Summary of environment variables

The following environment variable is required to run the HubSpot MCP server.

HUBSPOT_ACCESS_TOKEN — Access token for HubSpot application. Use a placeholder like your-access-token-here when configuring the MCP client. Example value: your-access-token-here.

crm_list_objects

List CRM objects with optional filtering and pagination.

crm_get_object

Retrieve a single CRM object by its ID.

crm_create_object

Create a new CRM object with validated properties.

crm_update_object

Update an existing CRM object.

crm_delete_object

Delete a CRM object.

crm_search_objects

Search CRM objects using advanced filters.

crm_batch_create_objects

Create multiple CRM objects in a single request.

crm_batch_update_objects

Update multiple CRM objects in a single request.

crm_batch_delete_objects

Delete multiple CRM objects in a single request.

crm_create_company

Create a new company with validated properties.

crm_update_company

Update an existing company.

crm_get_company

Get a single company by ID.

crm_search_companies

Search companies with specific filters.

crm_batch_create_companies

Create multiple companies in a single request.

crm_batch_update_companies

Update multiple companies in a single request.

crm_get_company_properties

Get all available company properties.

crm_create_company_property

Create a new company property.

crm_create_contact

Create a new contact with validated properties.

crm_update_contact

Update an existing contact's information.

crm_get_contact

Get a single contact by ID.

crm_search_contacts

Search contacts with specific filters.

crm_batch_create_contacts

Create multiple contacts in a single request.

crm_batch_update_contacts

Update multiple contacts in a single request.

crm_get_contact_properties

Get all available contact properties.

crm_create_contact_property

Create a new contact property.

crm_create_lead

Create a new lead with validated properties.

crm_update_lead

Update an existing lead's information.

crm_get_lead

Get a single lead by ID.

crm_search_leads

Search leads with specific filters.

crm_batch_create_leads

Create multiple leads in a single request.

crm_batch_update_leads

Update multiple leads in a single request.

crm_get_lead_properties

Get all available lead properties.

crm_create_lead_property

Create a new lead property.

engagement_details_get

Get details of a specific engagement.

engagement_details_create

Create a new engagement.

engagement_details_update

Update an existing engagement.

engagement_details_delete

Delete an engagement.

engagement_details_list

List all engagements with filtering.

engagement_details_get_associated

Get associated engagements.

calls_create

Create a new call record.

calls_get

Get call details.

calls_update

Update a call record.

calls_archive

Archive a call.

calls_list

List all calls.

calls_search

Search calls.

calls_batch_create

Create multiple calls.

calls_batch_read

Read multiple calls.

calls_batch_update

Update multiple calls.

calls_batch_archive

Archive multiple calls.

emails_create

Create a new email record.

emails_get

Get email details.

emails_update

Update an email.

emails_archive

Archive an email.

emails_list

List all emails.

emails_search

Search emails.

emails_batch_create

Create multiple emails.

emails_batch_read

Read multiple emails.

emails_batch_update

Update multiple emails.

emails_batch_archive

Archive multiple emails.

meetings_create

Create a new meeting.

meetings_get

Get meeting details.

meetings_update

Update a meeting.

meetings_delete

Delete a meeting.

meetings_list

List all meetings.

meetings_search

Search meetings.

meetings_batch_create

Create multiple meetings.

meetings_batch_update

Update multiple meetings.

meetings_batch_archive

Archive multiple meetings.

notes_create

Create a new note.

notes_get

Get note details.

notes_update

Update a note.

notes_archive

Archive a note.

notes_list

List all notes.

notes_search

Search notes.

notes_batch_create

Create multiple notes.

notes_batch_read

Read multiple notes.

notes_batch_update

Update multiple notes.

notes_batch_archive

Archive multiple notes.

tasks_create

Create a new task.

tasks_get

Get task details.

tasks_update

Update a task.

tasks_archive

Archive a task.

tasks_list

List all tasks.

tasks_search

Search tasks.

tasks_batch_create

Create multiple tasks.

tasks_batch_read

Read multiple tasks.

tasks_batch_update

Update multiple tasks.

tasks_batch_archive

Archive multiple tasks.

crm_list_association_types

List available association types.

crm_get_associations

Get all associations between objects.

crm_create_association

Create an association.

crm_delete_association

Delete an association.

crm_batch_create_associations

Create multiple associations.

crm_batch_delete_associations

Delete multiple associations.

communications_get_preferences

Get contact communication preferences.

communications_update_preferences

Update contact preferences.

communications_unsubscribe_contact

Global unsubscribe for a contact.

communications_subscribe_contact

Global subscribe for a contact.

communications_get_subscription_definitions

Get subscription definitions.

communications_get_subscription_status

Get status for multiple contacts.

communications_update_subscription_status

Update status for multiple contacts.

products_create

Create a product with given properties and return the object with ID.

products_read

Read a product by ID.

products_update

Partial update of a product by ID; empty values clear properties.

products_archive

Archive a product by ID.

products_list

Read a page of products with paging and properties control.

products_search

Search products.

products_batch_create

Create a batch of products.

products_batch_read

Read a batch of products by ID or unique properties.

products_batch_update

Update a batch of products by ID or unique values.

products_batch_archive

Archive a batch of products.