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:- Creating an app on the latest version of the developer platform (
2025.2
or higher). - 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.
- Configuring your MCP client to connect with the HubSpot MCP server using your HubSpot app’s OAuth token for authentication.
- 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:
- PKCE (Proof Key for Code Exchange)
- Refresh token rotation (single-use refresh tokens)
Behind the scenes, the HubSpot MCP server is based on the CRM search API, which currently doesn’t include vector search capabilities.
Prerequisites
- Before starting, you’ll need to join the HubSpot MCP server (remote) beta.
- Ensure you’ve installed the latest version of the HubSpot CLI (version
7.6.0
or later). You can check which version of the CLI you have by runninghs --version
.
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:With your app configured, upload it to your account by running
- The app’s
distribution
must be set tomarketplace
. - The app’s
auth
be set to useoauth
. - The app’s
isUserLevel
field must be set totrue
.
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 After adding scopes, upload the project with
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"
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.

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

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.

- In the top bar, select Tools.

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

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

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.