Skip to main content
Last modified: September 3, 2025
The HubSpot Model Context Protocol (MCP) server enables AI assistants and Large Language Models to securely interact with your HubSpot CRM data through natural conversation. By implementing the Model Context Protocol standard, this remote server acts as a bridge between AI systems and HubSpot’s APIs, allowing for intelligent automation and insights without requiring users to understand complex API structures. For developers, the remote HubSpot MCP server provides secure, granular access to HubSpot CRM data through AI agents and third-party applications, and allows teams to build custom workflows, automate reporting, and integrate HubSpot context into 3rd party applications. For end-users, it creates a more streamlined, simpler way to query their HubSpot data using natural language.
The HubSpot MCP server documented on this page is separate from the developer MCP server. The developer MCP server helps developers build apps and CMS content assets locally on HubSpot’s developer platform. In contrast, the HubSpot MCP server is intended for making requests to an account’s CRM data, similar to using HubSpot’s APIs.

​
Implementation overview

At a high level, integrating with the HubSpot MCP server involves:
  1. Creating an app on the latest version of the developer platform (2025.2 or higher).
  2. Installing the app in a HubSpot account that you want to fetch data from. Since the app will need to use OAuth authentication, you’ll need to set up an OAuth server.
  3. Configuring your MCP client to connect with the HubSpot MCP server using your HubSpot app’s OAuth token for authentication.
  4. Prompting your MCP client using natural language to query your HubSpot data.
Later in 2025, HubSpot will align with MCP specification requirements for OAuth 2.1 support. MCP clients connecting to HubSpot’s server will need to implement OAuth 2.1 authentication, including:To prepare for these changes, you should design your implementation to handle refresh tokens that change with each access token renewal. HubSpot will provide detailed migration guidance and timelines, as well as more details on using PKCE, ahead of the change.
The HubSpot MCP Server supports read-only access to the following CRM objects: contacts, companies, deals, tickets, carts, products, orders, line items, invoices, quotes, and subscriptions. The specific CRM object data that the MCP server can query is based on the scopes set in the app configuration and the user permissions granted to the user who installs the app. Unlike apps that are installed account-wide, apps that authenticate MCP server requests will need to be installed by each user.
Behind the scenes, the HubSpot MCP server is based on the CRM search API, which currently doesn’t include vector search capabilities.

​
Prerequisites

​
Set up your app

1

Create and configure an app

To get started, create an app on the latest version of the developer platform. Due to app configuration requirements, you won’t be able to use an existing app.Alternatively, start with HubSpot’s example app.Your app configuration will need to include the following:
  • The app’s distribution must be set to marketplace.
  • The app’s auth be set to use oauth.
  • The app’s isUserLevel field must be set to true.
{
  "uid": "user-level-app",
  "type": "app",
  "config": {
    "description": "A user level app template that can be used to 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": "support@example.com",
      "documentationUrl": "https://example.com/docs",
      "supportUrl": "https://example.com/support",
      "supportPhone": "+18005555555"
    }
  }
}
With your app configured, upload it to your account by running hs project upload. After this initial upload, you’ll add CRM app objects scopes that you want to include, then reupload.
2

Update CRM object app scopes

After your project is initially uploaded, add the CRM objects scopes that your app will be able to authenticate requests for. You’ll need to add the crm.objects.tickets.read scope as a requiredScope, but you can add any of the following scopes as either required or optional as needed."crm.objects.contacts.read","crm.objects.companies.read","crm.objects.deals.read", "crm.objects.carts.read", "crm.objects.products.read", "crm.objects.orders.read", "crm.objects.line_items.read", "crm.objects.invoices.read", "crm.objects.quotes.read", "crm.objects.subscriptions.read", "crm.objects.users.read", "crm.objects.owners.read"
  "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"
  ]
After adding scopes, upload the project with hs project upload.

​
Install the app

To install an OAuth marketplace app, make sure your OAuth server is fully set up, then proceed to the following steps.
Try using HubSpot’s sample OAuth app to get started with a basic OAuth server.
  • Navigate to the app’s distribution settings in HubSpot.
  • On the Distribution tab of your app settings, click Begin publishing.
  • Review and sign the Acceptable Use Policy (AUP). Until the AUP is signed, you won’t be able to install your app in accounts other than developer test accounts.
AUP panel for OAuth marketplace app
  • Close the right panel to return to the app management page without creating a marketplace listing for your app. You can return to the panel at any time by clicking Continue publishing.
  • Copy the install URL.
Unlisted OAuth marketplace app distribution settings
You can now use the install URL to install the app in a HubSpot account. The OAuth installation flow will generate an access token that you can provide to your preferred MCP client to connect with https://mcp.hubspot.com, along with a refresh token for generating new access tokens.
  • Don’t include any scopes as query parameters when sending the install URL. These scopes will be selected by the user during installation, and are no longer required to be included in the URL.
  • If you’re constructing the install URL in your backend, ensure it contains /user (e.g., https://mcp.hubspot.com/oauth/authorize/user).

​
Test the MCP server with MCP Inspector

To test the MCP server:
  • Run the MCP Inspector tool locally.
  • In the browser window that loads the MCP Inspector, configure the environment fields in the left sidebar as follows:
    • Transport Type: Streamable HTTP
    • URL: https://mcp.hubspot.com/
    • Bearer Token: your app’s access token (generated by the OAuth install flow)
    • Client ID: your app’s client ID.
  • Click Connect.
Once connected, the status will update to Connected and the main panel will display a set of options.
Screenshot of the MCP Inspector tool showing a successful connection
  • In the top bar, select Tools.
Screenshot of the Tools option in the MCP Inspector toolbar
  • Click List Tools.
  • In the tools list, scroll and select get_user_details. The right panel will display details about the tool.
  • Under the tool details in the right panel, click Run tool.
Screenshot of the Run tool button in the MCP inspector
  • After the tool runs, it will return a success message along with information about your user, the account you installed the app in, and will show object and tool data availability, based on the app’s scopes and your user permissions.
Screenshot of a successful response returned by the MCP Inspector
Not sure where to start with MCP clients? Check out this list of applications that support MCP integrations to find one that fits your needs.