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.

Tools

Core CRM Tools

1. hubspot_search_contacts

2. Search for contacts in HubSpot using a query string

3. Required inputs:
   • query (string): Search query string (email, name, etc.)
4. Optional inputs:
   • count (number, default: 10): Maximum number of contacts to return
   • propertyList (array): List of properties to include in results

5. Returns: List of matching contacts with their properties

6. hubspot_get_contact

7. Get a specific contact by ID

8. Required inputs:
   • contactId (string): The ID of the contact to retrieve
9. Optional inputs:
   • properties (array): List of properties to include in results

10. Returns: Contact details with specified properties

11. hubspot_create_contact

12. Create a new contact in HubSpot

13. Required inputs:
    • properties (object): Contact properties with at least email field

14. Returns: Created contact details

15. hubspot_update_contact

16. Update an existing contact in HubSpot

17. Required inputs:
    • contactId (string): The ID of the contact to update
    • properties (object): Contact properties to update

18. Returns: Updated contact confirmation

19. hubspot_list_deals

20. List deals in HubSpot with pagination

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

22. Returns: List of deals with their details

23. hubspot_get_deal

24. Get a specific deal by ID

25. Required inputs:
    • dealId (string): The ID of the deal to retrieve
26. Optional inputs:
    • properties (array): List of properties to include in results

27. Returns: Deal details with specified properties

28. hubspot_create_deal

29. Create a new deal in HubSpot

30. Required inputs:
    • properties (object): Deal properties with at least dealname field

31. Returns: Created deal details

32. hubspot_update_deal

33. Update an existing deal in HubSpot

34. Required inputs:
    • dealId (string): The ID of the deal to update
    • properties (object): Deal properties to update

35. Returns: Updated deal confirmation

36. hubspot_list_companies

37. List companies in HubSpot with pagination

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

39. Returns: List of companies with their details

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

1. Create a HubSpot Private App:

2. Go to your HubSpot account

3. Navigate to Settings → Account Setup → Integrations → Private Apps
4. Click "Create private app"
5. Name your app and set appropriate scopes (contacts, deals, and companies)

6. Create the app and copy your private app token

7. Required Scopes:

8. crm.objects.contacts.read
9. crm.objects.contacts.write
10. crm.objects.deals.read
11. crm.objects.deals.write
12. crm.objects.companies.read
13. crm.objects.companies.write
14. crm.objects.owners.read
15. crm.objects.quotes.read
16. crm.objects.line_items.read
17. crm.objects.custom.read
18. crm.schemas.deals.read
19. crm.schemas.contacts.read
20. crm.schemas.companies.read
21. crm.schemas.custom.read

Usage with Claude Desktop

Add the following to your claude_desktop_config.json:

npx

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

docker

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

Troubleshooting

If you encounter errors, verify that:

1. All required scopes are added to your HubSpot private app
2. The API key is correctly copied to your configuration
3. Your HubSpot plan includes access to the APIs you're trying to use

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.