HubSpot

You have an MCP server that enables Claude to interact with HubSpot CRM for sales analysis and insights. It exposes a set of tools to search contacts, manage deals, companies, and retrieve analytics so you can perform sales-focused queries and automation directly from your MCP client.

How to use

Use this server from your MCP client by loading one of the provided MCP configurations for running the hubspot server locally. You can run the server with either an npm-based execution via npx or in a Docker container. Once running, you can call the available tools to search contacts, manage deals and companies, and fetch analytics data to drive sales insights.

How to install

Prerequisites: install Node.js and/or Docker on your system. You will also need a HubSpot Private App with the required scopes. Follow these steps to set up the HubSpot MCP server locally.

Step 1: Create a HubSpot Private App and obtain an API key or access token with the necessary scopes.

Step 2: Run the MCP server using one of the available methods below.

Additional setup notes

Environment variable required by the MCP server: HUBSPOT_API_KEY. This value should be the private app API key/token you obtain from HubSpot.

The server configurations shown below are the recommended ways to start the MCP server locally. Choose either the npx-based start or the Docker-based start.

Security and usage notes

Ensure your HubSpot private app has the following scopes: crm.objects.contacts.read, crm.objects.contacts.write, crm.objects.deals.read, crm.objects.deals.write, crm.objects.companies.read, crm.objects.companies.write, crm.objects.owners.read, crm.objects.quotes.read, crm.objects.line_items.read, crm.objects.custom.read, crm.schemas.deals.read, crm.schemas.contacts.read, crm.schemas.companies.read, crm.schemas.custom.read.

Troubleshooting

If you encounter errors, verify that the HubSpot private app has all required scopes and that the API key is correctly configured in your MCP client. Also confirm your HubSpot plan includes access to the APIs you are trying to use.

Examples of starting the MCP server

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-hubspot"],
      "env": {
        "HUBSPOT_API_KEY": "your-api-key-here"
      }
    }
  }
}

{
  "mcpServers": {
    "hubspot": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "HUBSPOT_API_KEY", "mcp/hubspot"],
      "env": {
        "HUBSPOT_API_KEY": "your-api-key-here"
      }
    }
  }
}

Build

No separate build step is required when using the provided MCP start commands. Use the npx or Docker start blocks to run the server and interact with HubSpot data.

License

This MCP server is licensed under the MIT License. You may use, modify, and distribute it under the terms of that license.

Available tools

hubspot_search_contacts

Search for contacts in HubSpot using a query string. Requires query and optional count and propertyList. Returns matching contacts with their properties.

hubspot_get_contact

Retrieve a specific contact by ID. Optional properties can tailor the response.

hubspot_create_contact

Create a new contact with at least an email field. Returns the created contact details.

hubspot_update_contact

Update properties of an existing contact by ID. Returns an update confirmation.

hubspot_list_deals

List deals with pagination and optional property selection. Returns deal details.

hubspot_get_deal

Get a specific deal by ID with optional properties.

hubspot_create_deal

Create a new deal with at least a deal name. Returns created deal details.

hubspot_update_deal

Update a deal by ID with given properties. Returns update confirmation.

hubspot_list_companies

List companies with pagination and optional properties. Returns company details.

hubspot_get_company

Get a specific company by ID with optional properties.

hubspot_get_sales_analytics

Get aggregated sales analytics grouped by a time period with optional filters like pipeline, dealStage, and dealOwner.

hubspot_get_deal_history

Retrieve the complete history of changes to a deal with timestamps.

hubspot_get_deal_notes

Fetch notes associated with a deal with optional limit and pagination.

hubspot_get_engagements_by_deal

Get all engagement activities for a deal with optional type filtering and pagination.

hubspot_get_sales_performance

Get performance metrics for sales reps over a period with optional filters.

hubspot_get_pipeline_analytics

Get analytics for a specific pipeline including stage conversion metrics.

hubspot_get_forecast_analytics

Get forecasted sales data based on current pipeline and historical performance.