HubSpot MCP Server
This server enables Claude to manage HubSpot CRM records and generate sales insights.
Search, retrieve, create, and update HubSpot contacts.
List, retrieve, create, and update deals with pagination.
List and retrieve companies.
Get aggregated sales analytics by period, pipeline, stage, or owner.
Retrieve deal change history, notes, and engagement activities.
Analyze sales rep performance, pipeline conversion metrics, and future sales forecasts.
Enables interaction with the HubSpot CRM API, providing tools for managing contacts, deals, and companies, as well as accessing sales analytics data including performance metrics, pipeline analytics, deal history, and sales forecasting.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@HubSpot MCP Server search for contacts with email containing @acme.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
HubSpot MCP Server
MCP Server for the HubSpot API, enabling Claude to interact with HubSpot CRM for sales analysis and insights.
Disclaimer
This open-source project is not affiliated with or endorsed by HubSpot. It is an independent implementation that interacts with HubSpot's API.
Install from the MCP registry
Clients that support the MCP Registry can install io.github.scopiousdigital/hubspot-mcp. That entry runs the npm package @scopiousdigital/server-hubspot over stdio. Set HUBSPOT_API_KEY as described in Setup.
Need a custom HubSpot MCP server? Scopious Digital builds them.
Related MCP server: HubSpot MCP Server
Tools
Core CRM Tools
hubspot_search_contactsSearch for contacts in HubSpot using a query string
Required inputs:
query(string): Search query string (email, name, etc.)
Optional inputs:
count(number, default: 10): Maximum number of contacts to returnpropertyList(array): List of properties to include in results
Returns: List of matching contacts with their properties
hubspot_get_contactGet a specific contact by ID
Required inputs:
contactId(string): The ID of the contact to retrieve
Optional inputs:
properties(array): List of properties to include in results
Returns: Contact details with specified properties
hubspot_create_contactCreate a new contact in HubSpot
Required inputs:
properties(object): Contact properties with at leastemailfield
Returns: Created contact details
hubspot_update_contactUpdate an existing contact in HubSpot
Required inputs:
contactId(string): The ID of the contact to updateproperties(object): Contact properties to update
Returns: Updated contact confirmation
hubspot_list_dealsList deals in HubSpot with pagination
Optional inputs:
limit(number, default: 10, max: 100): Maximum number of deals to returnafter(string): Pagination cursor for next pageproperties(array): List of properties to include in results
Returns: List of deals with their details
hubspot_get_dealGet a specific deal by ID
Required inputs:
dealId(string): The ID of the deal to retrieve
Optional inputs:
properties(array): List of properties to include in results
Returns: Deal details with specified properties
hubspot_create_dealCreate a new deal in HubSpot
Required inputs:
properties(object): Deal properties with at leastdealnamefield
Returns: Created deal details
hubspot_update_dealUpdate an existing deal in HubSpot
Required inputs:
dealId(string): The ID of the deal to updateproperties(object): Deal properties to update
Returns: Updated deal confirmation
hubspot_list_companiesList companies in HubSpot with pagination
Optional inputs:
limit(number, default: 10, max: 100): Maximum number of companies to returnafter(string): Pagination cursor for next pageproperties(array): List of properties to include in results
Returns: List of companies with their details
hubspot_get_companyGet a specific company by ID
Required inputs:
companyId(string): The ID of the company to retrieve
Optional inputs:
properties(array): List of properties to include in results
Returns: Company details with specified properties
Sales Analytics Tools
hubspot_get_sales_analyticsGet aggregated sales analytics data for specific time periods
Required inputs:
period(string): Time period to group analytics data by (daily, weekly, monthly, quarterly, yearly)startDate(string): Start date for analysis in ISO format (YYYY-MM-DD)
Optional inputs:
endDate(string): End date for analysis in ISO formatpipeline(string): Pipeline ID to filter bydealStage(string): Deal stage ID to filter bydealOwner(string): Deal owner ID to filter by
Returns: Aggregated sales metrics grouped by time period
hubspot_get_deal_historyGet the complete history of changes to a deal
Required inputs:
dealId(string): The ID of the deal to get history for
Returns: History of deal changes with timestamps and modified properties
hubspot_get_deal_notesGet notes associated with a specific deal
Required inputs:
dealId(string): The ID of the deal to get notes for
Optional inputs:
limit(number, default: 20): Maximum number of notes to returnafter(string): Pagination cursor for next page of results
Returns: List of notes with their content and creation timestamps
hubspot_get_engagements_by_dealGet all engagement activities associated with a deal
Required inputs:
dealId(string): The ID of the deal to get engagements for
Optional inputs:
types(array): Types of engagements to include (CALL, EMAIL, MEETING, TASK, NOTE)limit(number, default: 20): Maximum number of engagements to returnafter(string): Pagination cursor for next page of results
Returns: List of engagements with their details and type information
hubspot_get_sales_performanceGet performance metrics for sales reps over a specific time period
Required inputs:
period(string): Time period to group performance data by (daily, weekly, monthly, quarterly, yearly)startDate(string): Start date for analysis in ISO format (YYYY-MM-DD)
Optional inputs:
endDate(string): End date for analysis in ISO formatownerIds(array): List of owner IDs to include in the analysispipeline(string): Pipeline ID to filter by
Returns: Performance metrics for each sales rep including deal counts, revenue, and win rates
hubspot_get_pipeline_analyticsGet analytics for a specific sales pipeline including conversion rates between stages
Required inputs:
pipelineId(string): The ID of the pipeline to analyzeperiod(string): Time period to group analytics data by (daily, weekly, monthly, quarterly, yearly)startDate(string): Start date for analysis in ISO format (YYYY-MM-DD)
Optional inputs:
endDate(string): End date for analysis in ISO format
Returns: Pipeline stage metrics including deal counts, values, conversion rates, and time in stage
hubspot_get_forecast_analyticsGet forecasted sales data based on current pipeline and historical performance
Required inputs:
period(string): Time period to group forecast data by (monthly, quarterly, yearly)
Optional inputs:
numberOfPeriods(number, default: 3): Number of future periods to forecastpipeline(string): Pipeline ID to filter by
Returns: Forecasted sales metrics for future periods based on historical data and current pipeline
Setup
Create a HubSpot service key and set it as HUBSPOT_API_KEY. HubSpot authenticates service keys as a bearer token (Authorization: Bearer <key>). This server passes HUBSPOT_API_KEY to the HubSpot client, which sends it in that header.
You must be a Super Admin, or have the Developer tools access permission, to create a key. A key can only be granted scopes you already have.
Create a service key:
In your HubSpot account, open Development
In the left sidebar, open Keys → Service keys. HubSpot's private app sunset also points here from Settings → Integrations → Service Keys
Click Create service key and enter a name
Click Add new scope. In the right panel, select each scope below. Use Find a scope to search by name
Click Update, review the list, then click Create and confirm
Open the new key, click Show, then Copy
Required scopes:
These match the CRM calls this server makes. Notes, calls, meetings, and tasks are read with
crm.objects.contacts.read. Deal pipeline analytics is covered bycrm.objects.deals.read.crm.objects.contacts.readcrm.objects.contacts.writecrm.objects.companies.readcrm.objects.deals.readcrm.objects.deals.writecrm.objects.owners.readsales-email-read(one-to-one email content, such ashs_email_text)
Existing legacy private app tokens still work in HUBSPOT_API_KEY until September 2027. HubSpot stopped new legacy private app creation on 28 September 2026 for new accounts and on 26 October 2026 for existing accounts, and legacy private apps become unsupported in September 2027. New setups should use a service key.
Usage with Claude Desktop
Add the following to your claude_desktop_config.json:
npx
{
"mcpServers": {
"hubspot": {
"command": "npx",
"args": ["-y", "@scopiousdigital/server-hubspot"],
"env": {
"HUBSPOT_API_KEY": "your-service-key"
}
}
}
}docker
{
"mcpServers": {
"hubspot": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "HUBSPOT_API_KEY", "mcp/hubspot"],
"env": {
"HUBSPOT_API_KEY": "your-service-key"
}
}
}
}Paste the copied service key (or an existing legacy private app token) as the value of HUBSPOT_API_KEY.
Troubleshooting
If you encounter errors, verify that:
Every scope listed above is on the service key
HUBSPOT_API_KEYis the key value from Show, not the key's nameYour HubSpot plan includes access to the APIs you're trying to use
The user who created the key already had those scopes
Build
Docker build:
docker build -t mcp/hubspot -f Dockerfile .License
This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
Maintained by Scopious Digital. We build HubSpot integrations and white-label dev for HubSpot agencies.
Available Tools
17 toolshubspot_create_contactC
Create a new contact in HubSpot
Inputs: properties (required).
hubspot_create_dealC
Create a new deal in HubSpot
Inputs: properties (required).
hubspot_get_companyC
Get a specific company by ID
Inputs: companyId (required), properties.
hubspot_get_contactC
Get a specific contact by ID
Inputs: contactId (required), properties.
hubspot_get_dealC
Get a specific deal by ID
Inputs: dealId (required), properties.
hubspot_get_deal_historyC
Get the complete history of changes to a deal
Inputs: dealId (required).
hubspot_get_deal_notesC
Get notes associated with a specific deal
Inputs: dealId (required), after, limit.
hubspot_get_engagements_by_dealB
Get all engagement activities (calls, emails, meetings, etc.) associated with a deal
Inputs: dealId (required), after, limit, types.
hubspot_get_forecast_analyticsC
Get forecasted sales data based on current pipeline and historical performance
Inputs: period (required), numberOfPeriods, pipeline.
hubspot_get_pipeline_analyticsB
Get analytics for a specific sales pipeline including conversion rates between stages
Inputs: period (required), pipelineId (required), startDate (required), endDate.
hubspot_get_sales_analyticsC
Get aggregated sales analytics data for specific time periods
Inputs: period (required), startDate (required), dealOwner, dealStage, +2 more.
hubspot_get_sales_performanceC
Get performance metrics for sales reps over a specific time period
Inputs: period (required), startDate (required), endDate, ownerIds, +1 more.
hubspot_list_companiesC
List companies in HubSpot with pagination
Inputs: after, limit, properties.
hubspot_list_dealsC
List deals in HubSpot with pagination
Inputs: after, limit, properties.
hubspot_search_contactsC
Search for contacts in HubSpot using a query string
Inputs: query (required), count, propertyList.
hubspot_update_contactC
Update an existing contact in HubSpot
Inputs: contactId (required), properties (required).
hubspot_update_dealC
Update an existing deal in HubSpot
Inputs: dealId (required), properties (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools have distinct purposes targeting specific HubSpot objects (contacts, deals, companies) and actions (create, get, list, update, search). However, some analytics tools like hubspot_get_forecast_analytics, hubspot_get_pipeline_analytics, hubspot_get_sales_analytics, and hubspot_get_sales_performance could be confusing due to overlapping 'analytics' terminology, though their descriptions help differentiate them.
All tools follow a consistent hubspot_verb_noun naming pattern with snake_case throughout. The verbs (create, get, list, search, update) are used predictably across different objects, making the set highly readable and systematic.
With 17 tools, the count is slightly high but reasonable for a comprehensive CRM integration covering contacts, deals, companies, and analytics. It's well-scoped for the domain, though it might feel heavy compared to simpler servers.
The tool set provides strong CRUD/lifecycle coverage for contacts and deals (create, get, list, update, search), with additional analytics and history tools. Minor gaps include no update for companies, no create for companies, and no delete operations, but agents can likely work around these omissions in typical workflows.
Related MCP Connectors
Solk CRM for Claude: accounts, pipeline, visits, quotes, orders and tickets with your permissions.
Sales-rep jobs on your HubSpot CRM: daily brief, triage, call prep, forecast. Writes need approval.
Create contacts, move deals, send proposals and invoices, read your inbox, from Claude or ChatGPT.
Manage your Elocuenti AI sales agents, CRM, campaigns and analytics from Claude.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI models to interact with HubSpot CRM data and operations through a standardized interface, supporting contact and company management.16129MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with HubSpot CRM for managing contacts, companies, deals, and sending emails through natural language commands.MIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables management of HubSpot CRM entities including contacts, companies, deals, and pipelines through natural language. It provides comprehensive tools for listing, searching, creating, and updating records with support for OAuth 2.0 authentication.MIT
- AlicenseNot gradedqualityDmaintenanceExposes CRM tools from HubSpot to Claude and other agents, enabling pipeline analysis, deal risk detection, and automated follow-up drafting.MIT