hubspot-mcp
HubSpot MCP provides a Model Context Protocol implementation for the HubSpot API, enabling efficient CRM data management. It offers extensive API coverage, batch operations, and advanced search capabilities, all with a type-safe interface.
HubSpot MCP
A Model Context Protocol (MCP) implementation for the HubSpot API, providing a standardized interface for accessing and managing CRM data.
Features
- Complete coverage of the HubSpot CRM API
- Support for all standard CRM objects (companies, contacts, deals, etc.)
- Advanced association management with CRM Associations v4
- Company-specific endpoints with property validation
- Batch operations for efficient data management
- Advanced search and filtering capabilities
- Type-safe parameter validation with Zod
Prerequisites
If you don't have an API key, follow the steps here to obtain an access token. OAuth support is planned as a future enhancement.
Client Configuration
There are several options to configure your MCP client with the server. For hosted/remote server setup, use Smithery's CLI with a Smithery API Key. For local installation, use npx
or build from source. Each of these options is explained below.
Smithery Remote Server (Recommended)
To add a remote server to your MCP client config.json
, run the following command from Smithery CLI:
npx -y @smithery/cli install @shinzo-labs/hubspot-mcp
Enter your HUBSPOT_ACCESS_TOKEN
when prompted.
Smithery SDK
If you are developing your own agent application, you can use the boilerplate code here.
NPX Local Install
To install the server locally with npx
, add the following to your MCP client config.json
:
{
"mcpServers": {
"hubspot": {
"command": "npx",
"args": [
"@shinzolabs/hubspot-mcp"
],
"env": {
"HUBSPOT_ACCESS_TOKEN": "your-access-token-here"
}
}
}
}
Build from Source
- Download the repo:
git clone https://github.com/shinzo-labs/hubspot-mcp.git
- Install packages (inside cloned repo):
pnpm i
- Add the following to your MCP client
config.json
:
{
"mcpServers": {
"hubspot": {
"command": "node",
"args": [
"/path/to/hubspot-mcp/index.js"
],
"env": {
"HUBSPOT_ACCESS_TOKEN": "your-access-token-here"
}
}
}
}
Config Variables
Variable | Description | Required? | Default |
---|---|---|---|
HUBSPOT_ACCESS_TOKEN | Access Token for Hubspot Application | Yes | |
PORT | Port for Streamable HTTP transport method | No | 3000 |
Supported Tools
Core CRM Objects
Basic Object Operations
crm_list_objects
: List CRM objects with optional filtering and paginationcrm_get_object
: Get a single CRM object by IDcrm_create_object
: Create a new CRM objectcrm_update_object
: Update an existing CRM objectcrm_delete_object
: Delete a CRM object
Search and Batch Operations
crm_search_objects
: Search CRM objects using advanced filterscrm_batch_create_objects
: Create multiple objects in a single requestcrm_batch_update_objects
: Update multiple objects in a single requestcrm_batch_delete_objects
: Delete multiple objects in a single request
CRM Records Management
Companies
- Basic Operations:
crm_create_company
: Create a new company with validated propertiescrm_update_company
: Update an existing companycrm_get_company
: Get a single company by IDcrm_search_companies
: Search companies with specific filters
- Batch Operations:
crm_batch_create_companies
: Create multiple companies in a single requestcrm_batch_update_companies
: Update multiple companies in a single request
- Property Management:
crm_get_company_properties
: Get all available company propertiescrm_create_company_property
: Create a new company property
Contacts
- Basic Operations:
crm_create_contact
: Create a new contact with validated propertiescrm_update_contact
: Update an existing contact's informationcrm_get_contact
: Get a single contact by IDcrm_search_contacts
: Search contacts with specific filters
- Batch Operations:
crm_batch_create_contacts
: Create multiple contacts in a single requestcrm_batch_update_contacts
: Update multiple contacts in a single request
- Property Management:
crm_get_contact_properties
: Get all available contact propertiescrm_create_contact_property
: Create a new contact property
Leads
- Basic Operations:
crm_create_lead
: Create a new lead with validated propertiescrm_update_lead
: Update an existing lead's informationcrm_get_lead
: Get a single lead by IDcrm_search_leads
: Search leads with specific filters
- Batch Operations:
crm_batch_create_leads
: Create multiple leads in a single requestcrm_batch_update_leads
: Update multiple leads in a single request
- Property Management:
crm_get_lead_properties
: Get all available lead propertiescrm_create_lead_property
: Create a new lead property
Engagement Management
Engagement Details
- Basic Operations:
engagement_details_get
: Get details of a specific engagementengagement_details_create
: Create a new engagementengagement_details_update
: Update an existing engagementengagement_details_delete
: Delete an engagementengagement_details_list
: List all engagements with filteringengagement_details_get_associated
: Get associated engagements
Calls
- Basic Operations:
calls_create
: Create a new call recordcalls_get
: Get call detailscalls_update
: Update a call recordcalls_archive
: Archive a callcalls_list
: List all callscalls_search
: Search calls
- Batch Operations:
calls_batch_create
: Create multiple callscalls_batch_read
: Read multiple callscalls_batch_update
: Update multiple callscalls_batch_archive
: Archive multiple calls
Emails
- Basic Operations:
emails_create
: Create a new email recordemails_get
: Get email detailsemails_update
: Update an emailemails_archive
: Archive an emailemails_list
: List all emailsemails_search
: Search emails
- Batch Operations:
emails_batch_create
: Create multiple emailsemails_batch_read
: Read multiple emailsemails_batch_update
: Update multiple emailsemails_batch_archive
: Archive multiple emails
Meetings
- Basic Operations:
meetings_create
: Create a new meetingmeetings_get
: Get meeting detailsmeetings_update
: Update a meetingmeetings_delete
: Delete a meetingmeetings_list
: List all meetingsmeetings_search
: Search meetings
- Batch Operations:
meetings_batch_create
: Create multiple meetingsmeetings_batch_update
: Update multiple meetingsmeetings_batch_archive
: Archive multiple meetings
Notes
- Basic Operations:
notes_create
: Create a new notenotes_get
: Get note detailsnotes_update
: Update a notenotes_archive
: Archive a notenotes_list
: List all notesnotes_search
: Search notes
- Batch Operations:
notes_batch_create
: Create multiple notesnotes_batch_read
: Read multiple notesnotes_batch_update
: Update multiple notesnotes_batch_archive
: Archive multiple notes
Tasks
- Basic Operations:
tasks_create
: Create a new tasktasks_get
: Get task detailstasks_update
: Update a tasktasks_archive
: Archive a tasktasks_list
: List all taskstasks_search
: Search tasks
- Batch Operations:
tasks_batch_create
: Create multiple taskstasks_batch_read
: Read multiple taskstasks_batch_update
: Update multiple taskstasks_batch_archive
: Archive multiple tasks
Associations and Relationships
CRM Associations v4
- Basic Operations:
crm_list_association_types
: List available association typescrm_get_associations
: Get all associations between objectscrm_create_association
: Create an associationcrm_delete_association
: Delete an association
- Batch Operations:
crm_batch_create_associations
: Create multiple associationscrm_batch_delete_associations
: Delete multiple associations
Communication Preferences
Subscription Management
- Basic Operations:
communications_get_preferences
: Get contact preferencescommunications_update_preferences
: Update contact preferencescommunications_unsubscribe_contact
: Global unsubscribecommunications_subscribe_contact
: Global subscribecommunications_get_subscription_definitions
: Get subscription definitions
- Bulk Operations:
communications_get_subscription_status
: Get status for multiple contactscommunications_update_subscription_status
: Update status for multiple contacts
Products
Basic Operations:
products_create
: Create a product with the given properties and return a copy of the object, including the ID.products_read
: Read an Object identified by IDproducts_update
: Perform a partial update of an Object identified by ID. Read-only and non-existent properties will result in an error. Properties values can be cleared by passing an empty string.products_archive
: Move an Object identified by ID to the recycling bin.products_list
: Read a page of products. Control what is returned via theproperties
query param.after
is the paging cursor token of the last successfully read resource will be returned as thepaging.next.after
JSON property of a paged response containing more results.products_search
: Search products
Batch Operations:
products_batch_create
: Create a batch of productsproducts_batch_read
: Read a batch of products by internal ID, or unique property values. Retrieve records by theidProperty
parameter to retrieve records by a custom unique value property.products_batch_update
: Update a batch of products by internal ID, or unique values specified by theidProperty
query param.products_batch_archive
: Archive a batch of products by ID
Contributing
Contributions are welcomed and encouraged! Please read for guidelines on issues, contributions, and contact information.