Integrate AI tools with the HubSpot MCP server

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 third-party applications. For end-users, it creates a more streamlined, simpler way to query their HubSpot data using natural language. For guidance on when to use the HubSpot MCP server, check out recommended use cases.

​

Implementation overview

At a high level, integrating with the HubSpot MCP server involves:

1. Creating an MCP connector in your HubSpot account.
2. Configuring your MCP client to connect to the HubSpot MCP server at https://mcp.hubspot.com using your connector’s OAuth credentials.
3. Prompting your MCP client using natural language to query your HubSpot data.

Once you’ve created your MCP connector, you can use it with any MCP client that supports OAuth authentication with PKCE (Proof Key for Code Exchange). PKCE is required for authenticating with HubSpot’s MCP server.

​

Supported data and permissions

The following data is accessible via the remote MCP server.

​

Read access

• CRM records: contacts, companies, deals, tickets, leads, users, appointments, courses, listings, projects, services, custom objects, and segments (lists). Revenue objects (carts, invoices, orders, line items, products, quotes, subscriptions) are available in BETA.
• Activities: calls, emails, meetings, notes, and tasks.
• Content and marketing: blog posts, landing pages, site pages, campaigns, and marketing events.
• Content analytics: conversion rates, submissions, and views for landing pages, website pages, and blog posts.
• Conversations: messages and threads from live chat, team email, WhatsApp, SMS, Facebook Messenger, and custom channels connected to help desk or conversations inbox.

• Marketing emails: draft emails and previews, email analytics data including aggregate send statistics (sends, opens, clicks, bounces, unsubscribes, and deliveries), account email health diagnostics, and per-contact delivery and engagement details.
• User and account: authenticated user details and permissions, account information, and organization-wide data including teams, job titles, and seat counts.
• AEO: brand-level metrics, share of voice, tracked prompt performance, and full AI engine response text from ChatGPT, Gemini, Perplexity, and Claude. Available in HubSpot accounts with a Marketing Hub Professional or Enterprise subscription.

​

Write access

• CRM records: create and edit contacts, companies, deals, tickets, leads, line items, products, appointments, courses, listings, projects, services, and custom object records. When creating or updating CRM records, the MCP server respects conditional field logic, including custom pipeline stage validations.
• Activities: calls, emails, meetings, notes, and tasks.
• Content: create, edit, and publish landing pages, website pages, and blog posts.
• Campaigns: create and update campaigns and manage campaign asset associations.
• Marketing emails: create and update email drafts.
• Pipelines: create and manage pipelines for supported objects. For HubSpot accounts with free tools, creating custom pipelines is not supported, but this tool can edit the default HubSpot-provided pipeline.
• Properties: create custom properties for CRM objects.
• Quotes (BETA): create and manage quotes. Requires the manage revenue objects optional scope and is available in HubSpot accounts with a Revenue Hub Professional or Enterprise subscription.
• Segments: create static segments and add or remove records from existing segments.
• AEO: create tracked prompts and act on brand recommendations, including starting content generation actions such as blog posts and social posts. Available in HubSpot accounts with a Marketing Hub Professional or Enterprise subscription.

​

Permissions and scopes

All actions respect your existing HubSpot user permissions. Users can only view and modify records they have access to in HubSpot. When creating an MCP connector, it’s important to note that you don’t explicitly define the connector’s scopes. Instead, available scopes are automatically determined by two factors:

• The tools available in the MCP server at the time of installation.
• The permissions that the user chooses to grant during installation.

As the MCP server’s tools are updated, the available scopes may change. In the event of scope updates, users who have already installed the connector will need to re-install to grant any new scopes.

​

Available tools

Tool availability varies by HubSpot subscription, user permissions, and account configuration. Run get_user_details after connecting to check which tools and objects are available for your specific account. The list below covers publicly available tools; some MCP clients may offer additional provider-specific tools not listed here.

​

Create an MCP connector

Create an MCP connector in your HubSpot account.

• In the main navigation bar of your HubSpot account, navigate to Development.
• In the left sidebar menu, navigate to MCP Connectors.
• In the upper right, click Create MCP connector.
• In the dialog box, enter your connector details, which you can update later as needed:
  • Name: the name of your connector.
  • Description: an optional description of your connector.
  • Redirect URL: the URL to use for OAuth authentication. If you’ll be testing with the MCP inspector, you’ll need to include http://localhost:6274/oauth/callback/debug as a redirect URL.
  • Icon: an optional icon for your connector.
• Click Create.

HubSpot will then generate a connector configured with OAuth authentication using the details you provided. You’ll then be redirected to the connector’s details page, where you can view its client credentials, redirect URLs, and more. To edit your connector details, you can click Edit info in the upper right. You can then proceed to connect your MCP client to the HubSpot MCP server, using your connector to authenticate requests. For quick testing, you can use the MCP inspector tool, as described in the next section. Otherwise, you can continue to the General MCP client connection section for general instructions.

​

Test with the MCP inspector

The MCP Inspector is a debugging tool that handles OAuth with PKCE automatically, making it a quick way to test your connection to HubSpot’s MCP server without building a full integration. To connect using MCP Inspector:

1. Run the MCP Inspector tool locally.
2. Configure the connection using the Streamable HTTP transport type, with the URL set to https://mcp.hubspot.com/, and enter your connector’s client ID and client secret.
3. Open the OAuth settings and complete the guided OAuth flow, which will direct you to authorize your HubSpot account.
4. Once authentication is complete, connect to the server and use the List Tools option to view available tools.

To verify your connection, run the get_user_details tool. A successful response will return information about your user, account, and available object and tool access.

​

General MCP client connection instructions

After creating your MCP connector, you can connect your MCP client to https://mcp.hubspot.com using your connector’s credentials. Your MCP client will need to handle the OAuth flow, including PKCE, to authenticate with HubSpot. To configure your MCP client, you’ll need the following from your connector’s details page:

• Client ID
• Client secret
• Redirect URL (must match what’s configured in your MCP client)

During the OAuth flow, you will:

1. Select the HubSpot account to connect.
2. Grant permissions to the connector. These permissions are based on the user’s permissions in HubSpot and determine what data the connector can access.
3. Authorize the connection.

Once authorized, your MCP client can make requests to the HubSpot MCP server on behalf of the authenticated user.

​

Troubleshooting

​

PKCE-related authentication failures

HubSpot’s MCP server requires PKCE (Proof Key for Code Exchange) for all OAuth authentication flows. If your MCP client doesn’t handle PKCE automatically, you’ll need to implement it yourself:

• Generate a random code_verifier (43-128 characters).
• Derive the code_challenge from the verifier using the S256 method.
• Include the code_challenge and code_challenge_method=S256 in the authorization request.
• Include the code_verifier in the token exchange request.

If you see authentication errors during the OAuth flow, verify that your client is correctly generating and sending the PKCE parameters. Some MCP clients, like the MCP Inspector, handle PKCE automatically.

​

Token refresh failures

OAuth access tokens expire after a set period. If your MCP client stops working after a period of inactivity:

• Ensure your client is using the refresh_token returned during the initial OAuth flow to request a new access token.
• If the refresh token has also expired or been invalidated, you’ll need to re-run the full OAuth authorization flow.
• Check that your redirect URL in the MCP client matches the redirect URL configured in your MCP connector in HubSpot.