HubSpot MCP

How to Install and Use HubSpot MCP

HubSpot MCP helps you connect AI assistants and other tools to your HubSpot CRM data using natural language. This guide will walk you through installing and setting up the HubSpot MCP app step by step with practical examples.

Step 1: Create and Configure Your App

First, you need to create a new app on HubSpot’s developer platform. This app will let HubSpot MCP connect to your CRM securely.

When setting up your app, remember these important points:

• Your app distribution must be set to "marketplace".
• Authentication (auth) should use "oauth".
• The app needs "isUserLevel" set to true so each user can install it individually.

Here is a simple example of how your app configuration (in app.json or similar) should look:

{
  "uid": "user-level-app",
  "type": "app",
  "config": {
    "description": "A user level app template that can connect with HubSpot MCP server",
    "name": "user level app",
    "distribution": "marketplace",
    "isUserLevel": true,
    "auth": {
      "type": "oauth",
      "redirectUrls": [
        "http://localhost",
        "http://localhost:3000/oauth-callback",
        "https://oauth.myapplication.com/oauth-callback"
      ],
      "requiredScopes": [
        "oauth",
        "crm.objects.contacts.read",
        "crm.objects.companies.read",
        "crm.objects.deals.read"
      ],
      "optionalScopes": []
    },
    "permittedUrls": {
      "fetch": ["https://api.hubapi.com"],
      "iframe": [],
      "img": []
    },
    "support": {
      "supportEmail": "[email protected]",
      "documentationUrl": "https://example.com/docs",
      "supportUrl": "https://example.com/support",
      "supportPhone": "+18005555555"
    }
  }
}

After configuring your app, use the HubSpot CLI to upload it by running:

hs project upload

Step 2: Update CRM Object Scopes

After your app is uploaded once, you need to add the specific CRM data your app should access. This means adding reading permissions (scopes) for the objects you want, such as contacts, companies, deals, and tickets.

For example, add these scopes to your app configuration:

"requiredScopes": [
  "oauth",
  "crm.objects.contacts.read",
  "crm.objects.companies.read",
  "crm.objects.tickets.read"
],
"optionalScopes": [
  "crm.objects.products.read",
  "crm.objects.orders.read",
  "crm.objects.line_items.read"
]

Once updated, upload your project again with:

hs project upload

Step 3: Install the App Using the OAuth Flow

To start using HubSpot MCP, install the app into your HubSpot account. You need to have an OAuth server set up for your app to handle authentication. If you need an example OAuth server, HubSpot’s sample OAuth app can help you get started: https://github.com/HubSpot/sample-apps-oauth.

To install:

• Go to your app’s distribution settings in HubSpot.
• Click Begin publishing on the Distribution tab.
• Review and sign the Acceptable Use Policy (AUP).
• Copy the install URL provided after publishing steps.

Make sure you:

• Do not add any scopes in the URL’s query parameters. Users select this during installation.
• The installation URL should include /user, for example:

https://mcp.hubspot.com/oauth/authorize/user

When users install the app, OAuth tokens will be generated. These tokens authenticate your MCP client with HubSpot MCP server.

Step 4: Test HubSpot MCP Server with MCP Inspector

Once installed, you can test your connection using the MCP Inspector tool:

1. Download and run the MCP Inspector locally: https://github.com/modelcontextprotocol/inspector.
2. In the MCP Inspector browser window:
   • Set Transport Type to Streamable HTTP.
   • Set URL to https://mcp.hubspot.com/.
   • Enter your app’s Bearer Token (from OAuth).
   • Enter your app’s Client ID.
3. Click Connect.

After connecting:

• Go to the Tools menu.
• Click List Tools.
• Select the get_user_details tool.
• Click Run tool.

You will see a success message along with info about your user, account, and available data, confirming your MCP app is working properly.

---

Following these steps, you can install and start using HubSpot MCP to enable AI tools to read and work with your HubSpot CRM data easily and securely.