HubSpot MCP Tools & API Patterns

Overview

HubSpot provides a first-party remote MCP server at https://mcp.hubspot.com/ for AI tool integration. The MCP server uses OAuth 2.0 with PKCE for authentication and Streamable HTTP as its transport protocol. Tools are backed by the HubSpot CRM Search API and cover contacts, companies, deals, tickets, tasks, notes, and associations. This skill covers MCP server connection, the complete tool reference, search patterns, error handling, and best practices.

Connection & Authentication

MCP Server

HubSpot hosts an official remote MCP server. Authentication uses OAuth 2.0 with PKCE, handled by the mcp-remote bridge:

Go to developers.hubspot.com
Navigate to Development > MCP Auth Apps
Create a new MCP Auth App
Copy the Client ID and Client Secret

MCP Server URL: https://mcp.hubspot.com/

Transport: Streamable HTTP

Authentication: OAuth 2.0 + PKCE (handled automatically by mcp-remote)

Environment Variables

export HUBSPOT_CLIENT_ID="your-client-id"
export HUBSPOT_CLIENT_SECRET="your-client-secret"

Claude Desktop Configuration

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.hubspot.com/"
      ],
      "env": {
        "HUBSPOT_CLIENT_ID": "YOUR_CLIENT_ID",
        "HUBSPOT_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

Scopes

HubSpot MCP automatically derives required OAuth scopes from the tools you use. You do not need to manually configure scopes. For example:

Using contact tools automatically requests crm.objects.contacts.read and crm.objects.contacts.write
Using deal tools automatically requests crm.objects.deals.read and crm.objects.deals.write
Using association tools automatically requests the appropriate association scopes

Sensitive Data

HubSpot MCP excludes sensitive data properties (PHI -- Protected Health Information) from tool responses by default. Properties marked as sensitive in HubSpot settings will not appear in MCP tool results.

Complete MCP Tool Reference

Contact Tools

Tool	Description	Key Parameters
`hubspot_retrieve_contact`	Get a single contact by ID	`contactId` (required)
`hubspot_create_contact`	Create a new contact	`email` (required), `firstname`, `lastname`, `phone`, `company`
`hubspot_update_contact`	Update an existing contact	`contactId` (required), property fields to update
`hubspot_list_contacts`	List contacts with pagination	`limit`, `after` (cursor)
`hubspot_list_contact_properties`	List all contact properties	None
`hubspot_search_contacts`	Search contacts by criteria	`filterGroups`, `sorts`, `limit`, `after`

Company Tools

Tool	Description	Key Parameters
`hubspot_retrieve_company`	Get a single company by ID	`companyId` (required)
`hubspot_create_company`	Create a new company	`name` (required), `domain`, `industry`, `phone`
`hubspot_update_company`	Update an existing company	`companyId` (required), property fields to update
`hubspot_list_company_properties`	List all company properties	None
`hubspot_search_companies`	Search companies by criteria	`filterGroups`, `sorts`, `limit`, `after`

Deal Tools

Tool	Description	Key Parameters
`hubspot_retrieve_deal`	Get a single deal by ID	`dealId` (required)
`hubspot_create_deal`	Create a new deal	`dealname` (required), `amount`, `dealstage`, `pipeline`
`hubspot_update_deal`	Update an existing deal	`dealId` (required), property fields to update
`hubspot_list_deal_properties`	List all deal properties	None
`hubspot_search_deals`	Search deals by criteria	`filterGroups`, `sorts`, `limit`, `after`

Ticket Tools

Tool	Description	Key Parameters
`hubspot_retrieve_ticket`	Get a single ticket by ID	`ticketId` (required)
`hubspot_create_ticket`	Create a new ticket	`subject` (required), `content`, `hs_pipeline`, `hs_pipeline_stage`
`hubspot_update_ticket`	Update an existing ticket	`ticketId` (required), property fields to update

Activity Tools

Tool	Description	Key Parameters
`hubspot_create_task`	Create a task	`hs_task_subject` (required), `hs_task_body`, `hs_task_priority`, `hs_timestamp`
`hubspot_create_note`	Create a note	`hs_note_body` (required), `hs_timestamp`

Utility Tools

Tool	Description	Key Parameters
`hubspot_open_hubspot_ui`	Open HubSpot UI for an object	`objectType`, `objectId`
`hubspot_get_user_details`	Get details of the current user	None

Association Tools

Tool	Description	Key Parameters
`hubspot_create_association`	Create an association between objects	`fromObjectType`, `fromObjectId`, `toObjectType`, `toObjectId`, `associationType`
`hubspot_access_associations`	List associations for an object	`objectType`, `objectId`, `toObjectType`

CRM Search API

Search Patterns

HubSpot MCP tools that search records use the CRM Search API under the hood. Search tools accept filterGroups for structured queries:

Filter Group Structure:

{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "email",
          "operator": "CONTAINS_TOKEN",
          "value": "acme.com"
        }
      ]
    }
  ]
}

Available Operators

Operator	Description	Example
`EQ`	Equals	`{"propertyName": "lifecyclestage", "operator": "EQ", "value": "customer"}`
`NEQ`	Not equals	`{"propertyName": "lifecyclestage", "operator": "NEQ", "value": "subscriber"}`
`LT`	Less than	`{"propertyName": "amount", "operator": "LT", "value": "1000"}`
`LTE`	Less than or equal	`{"propertyName": "amount", "operator": "LTE", "value": "5000"}`
`GT`	Greater than	`{"propertyName": "amount", "operator": "GT", "value": "10000"}`
`GTE`	Greater than or equal	`{"propertyName": "createdate", "operator": "GTE", "value": "2026-01-01"}`
`CONTAINS_TOKEN`	Contains token (word match)	`{"propertyName": "email", "operator": "CONTAINS_TOKEN", "value": "acme"}`
`NOT_CONTAINS_TOKEN`	Does not contain token	`{"propertyName": "email", "operator": "NOT_CONTAINS_TOKEN", "value": "test"}`
`HAS_PROPERTY`	Property has a value	`{"propertyName": "phone", "operator": "HAS_PROPERTY"}`
`NOT_HAS_PROPERTY`	Property has no value	`{"propertyName": "phone", "operator": "NOT_HAS_PROPERTY"}`
`IN`	Value in list	`{"propertyName": "dealstage", "operator": "IN", "values": ["stage1", "stage2"]}`
`NOT_IN`	Value not in list	`{"propertyName": "dealstage", "operator": "NOT_IN", "values": ["closedlost"]}`
`BETWEEN`	Between two values	`{"propertyName": "amount", "operator": "BETWEEN", "value": "1000", "highValue": "5000"}`

Sorting

{
  "sorts": [
    {
      "propertyName": "createdate",
      "direction": "DESCENDING"
    }
  ]
}

Sort Directions: ASCENDING, DESCENDING

Pagination

Search results use cursor-based pagination:

Parameter	Description	Default	Max
`limit`	Results per page	10	100
`after`	Cursor for next page	None	-

Iterating through all results:

Call the search tool with limit=100
Check the response for a paging.next.after value
If present, call again with after set to that value
Repeat until no paging.next.after is returned

Response Format

Single Resource:

{
  "id": "12345",
  "propertie

HubSpot API Patterns

How to add

Drop this on your repo README

Related skills

pdf

pptx

docx

canvas-design

Get new Documentos skills every Monday