Skip to main content
Glama

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

  1. hubspot_search_contacts

    • Search 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 return

      • propertyList (array): List of properties to include in results

    • Returns: List of matching contacts with their properties

  2. hubspot_get_contact

    • Get 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

  3. hubspot_create_contact

    • Create a new contact in HubSpot

    • Required inputs:

      • properties (object): Contact properties with at least email field

    • Returns: Created contact details

  4. hubspot_update_contact

    • Update an existing contact in HubSpot

    • Required inputs:

      • contactId (string): The ID of the contact to update

      • properties (object): Contact properties to update

    • Returns: Updated contact confirmation

  5. hubspot_list_deals

    • List deals in HubSpot with pagination

    • Optional inputs:

      • limit (number, default: 10, max: 100): Maximum number of deals to return

      • after (string): Pagination cursor for next page

      • properties (array): List of properties to include in results

    • Returns: List of deals with their details

  6. hubspot_get_deal

    • Get 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

  7. hubspot_create_deal

    • Create a new deal in HubSpot

    • Required inputs:

      • properties (object): Deal properties with at least dealname field

    • Returns: Created deal details

  8. hubspot_update_deal

    • Update an existing deal in HubSpot

    • Required inputs:

      • dealId (string): The ID of the deal to update

      • properties (object): Deal properties to update

    • Returns: Updated deal confirmation

  9. hubspot_list_companies

    • List companies in HubSpot with pagination

    • Optional inputs:

      • limit (number, default: 10, max: 100): Maximum number of companies to return

      • after (string): Pagination cursor for next page

      • properties (array): List of properties to include in results

    • Returns: List of companies with their details

  10. hubspot_get_company

    • Get 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

  1. hubspot_get_sales_analytics

    • Get 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 format

      • pipeline (string): Pipeline ID to filter by

      • dealStage (string): Deal stage ID to filter by

      • dealOwner (string): Deal owner ID to filter by

    • Returns: Aggregated sales metrics grouped by time period

  2. hubspot_get_deal_history

    • Get 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

  3. hubspot_get_deal_notes

    • Get 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 return

      • after (string): Pagination cursor for next page of results

    • Returns: List of notes with their content and creation timestamps

  4. hubspot_get_engagements_by_deal

    • Get 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 return

      • after (string): Pagination cursor for next page of results

    • Returns: List of engagements with their details and type information

  5. hubspot_get_sales_performance

    • Get 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 format

      • ownerIds (array): List of owner IDs to include in the analysis

      • pipeline (string): Pipeline ID to filter by

    • Returns: Performance metrics for each sales rep including deal counts, revenue, and win rates

  6. hubspot_get_pipeline_analytics

    • Get analytics for a specific sales pipeline including conversion rates between stages

    • Required inputs:

      • pipelineId (string): The ID of the pipeline to analyze

      • 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 format

    • Returns: Pipeline stage metrics including deal counts, values, conversion rates, and time in stage

  7. hubspot_get_forecast_analytics

    • Get 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 forecast

      • pipeline (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.

  1. 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

  2. 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 by crm.objects.deals.read.

    • crm.objects.contacts.read

    • crm.objects.contacts.write

    • crm.objects.companies.read

    • crm.objects.deals.read

    • crm.objects.deals.write

    • crm.objects.owners.read

    • sales-email-read (one-to-one email content, such as hs_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:

  1. Every scope listed above is on the service key

  2. HUBSPOT_API_KEY is the key value from Show, not the key's name

  3. Your HubSpot plan includes access to the APIs you're trying to use

  4. 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 tools
hubspot_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

    B3.3/5.0

    Scored across 17 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI models to interact with HubSpot CRM data and operations through a standardized interface, supporting contact and company management.
      16
      129
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      Exposes CRM tools from HubSpot to Claude and other agents, enabling pipeline analysis, deal risk detection, and automated follow-up drafting.
      MIT