> ## Documentation Index > Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt > Use this file to discover all available pages before exploring further. --- id: b482f855-dafa-419c-bfa2-18b6cf080d8c --- # Integrate AI tools with the HubSpot MCP server > Learn how to configure a connector to authenticate requests to the HubSpot MCP server for interacting with HubSpot's APIs. 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](https://modelcontextprotocol.io/docs/2026-07-28/getting-started/intro) 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](https://developers.hubspot.com/docs/build-with-ai/remote-mcp-server.md). > [!NOTE] > > The HubSpot MCP server documented on this page is separate from the [developer MCP server](https://developers.hubspot.com/docs/developer-tooling/local-development/developer-mcp/setup.md). 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 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](https://datatracker.ietf.org/doc/html/rfc7636) (Proof Key for Code Exchange). PKCE is required for authenticating with HubSpot's MCP server. > [!NOTE] > > Some MCP clients, like the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), handle PKCE automatically. If you're building a custom integration, ensure your OAuth implementation includes PKCE support. Learn more about [OAuth 2.1 authorization in the MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization). ## Supported data and permissions The following data is accessible via the remote MCP server. > [!WARNING] > > **Please note:** if your HubSpot account has [Sensitive Data](https://developers.hubspot.com/docs/api-reference/latest/crm/properties/sensitive-data.md) turned on, activity (e.g., calls, emails, meetings, notes, and tasks) and conversation data will be blocked from access through the MCP server. This restriction is specific to the MCP server and does not apply to the standard CRM APIs. ### 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. > [!NOTE] > > Conversations access has additional restrictions based on your HubSpot inbox configuration. > > * Help desk conversations are visible to all users. > * For the conversations inbox, if access has been restricted to specific users or teams, only those users can query those conversations through the MCP server. * **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. * **Social:** list your connected social accounts, browse scheduled and published posts, and view post performance data. * **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. > [!NOTE] > > Behind the scenes, the HubSpot MCP server is based on the [CRM search API](https://developers.hubspot.com/docs/api-reference/latest/crm/search-the-crm.md), which currently doesn't include vector search capabilities. ### 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. * **Social:** create drafts, schedule posts, update or cancel scheduled posts, upload local media, preview posts before publishing, and assign posts to campaigns. > [!NOTE] > > To create or modify social posts through the MCP server, you must grant the `social.publish` scope. The `social.read` and `social.edit` scopes only provide read-only access. ### 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. > [!NOTE] > > Claude Enterprise admins can restrict connector access to company-provisioned accounts only by enabling verified domain restrictions in their account settings. ### 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.
`get_user_details`
Returns the authenticated user's information, account details, and per-object access (read and write).
`get_organization_details`
Lists organization-wide teams, job titles, seat counts, and account information including timezone, currency, and account type.
`discover_hubspot_schema`
Search HubSpot schema to discover available object types, or look up specific known types directly. Returns type names and read and write access status based on user permissions.
`search_crm_objects`
Search and filter CRM records using filter groups, text queries, sorting, and pagination. Based on the [CRM search API](https://developers.hubspot.com/docs/api-reference/latest/crm/search-the-crm.md). Supports up to five filter groups with up to six filters each. Filters within a group use AND logic, and groups are combined using OR logic. Maximum 200 results per page.
`get_crm_objects`
Fetch one or more CRM objects by their IDs in a single request. Maximum 100 object IDs per request.
`manage_crm_objects`
Create or update CRM records or activities. Before writing, check write availability for the target object using `get_user_details`. The tool presents a proposed-changes summary for user review and requires explicit user confirmation before executing any create or update. For association and association label operations, call `tool_guidance` first.
`manage_segment`
Create static and dynamic segments. For static segments, also supports adding and removing CRM records from existing segments. Requires explicit user confirmation before each write.
`query_crm_data`
Query HubSpot CRM data using SQL with HubSpot-specific extensions. Supports filtering, aggregation, and sorting. Call `tool_guidance` before the first query to understand syntax and limitations. Confirm property names with `search_properties` before querying. Does not support joins, column aliases, subqueries, association traversal, or currency conversion.
`search_properties`
Find property definitions for an object type using keyword search. Returns property names, labels, and descriptions. Maximum 5 keywords per request.
`get_properties`
Get full property definitions, including data types and enumeration values. Responses can be large, so it's recommended to fetch specific properties by name when possible.
`manage_custom_properties`
Create custom properties for CRM objects.
`manage_custom_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.
`search_owners`
Find CRM record owners by name or email, or look up owners by ID. Maximum 100 results.
`get_campaign_attribution_reports`
Get revenue and deal attribution data for campaigns. Attribution reports are scoped to closed-won deal attribution only. For general campaign engagement metrics or all-stage deal data, use `read_campaign_data` instead. Call `tool_guidance` before first use to understand required parameters. Supports long-running queries with polling.
`read_campaign_data`
Read campaign analytics, asset metrics, or contact data in a single operation. Use the tool's built-in guidance to get the required parameter details before calling.
`manage_campaign_objects`
Create or update marketing campaigns and manage campaign asset associations. Requires user confirmation before creating or modifying campaigns.
`search_conversations`
Search conversations and messages from HubSpot inboxes. Supports lookup by CRM object, time range, or keyword, and aggregation by channel, inbox, or status.
`get_conversation_channel_metadata`
List the inboxes, channels, and channel instances available in the account. Call this before using `search_conversations` to filter by channel, inbox, or instance IDs.
`search_intent_signals`
Search and analyze buyer intent signals for companies and contacts. Supports searching for signal records, listing the account's signal types, and aggregating signal counts by company.
`get_marketing_email_analytics`
Get analytics data for marketing emails based on sends within a given date range. Supports three modes: account-level aggregate statistics (sends, deliveries, opens, clicks, bounces, and unsubscribes), account email health diagnostics by MX group, and per-contact delivery and engagement details for a specific email send.
`manage_marketing_email`
Manage marketing email settings and content. Supports: * Listing available templates, subscription types, and from addresses * Creating, updating, and cloning email drafts * Retrieving, editing, and previewing email content * Managing A/B variants. > [!NOTE] > > Creating and updating email drafts requires the following connector permissions: > > * View properties about the installing account including primary domain and user emails > * See details about this account's teams > * Create and edit marketing email content
`get_content_analytics_report`
Run content analytics across landing pages, website pages, and blog posts. Supports totals, time series, summary aggregates, and viewer lookups.
`manage_landing_page`
Create, edit, style, publish, clone, and inspect landing pages. Supports reading module types and templates, and writing content, styles, and metadata. Writes are sequential. Requires user confirmation before creating a page from a template, publishing, or restoring a revision. After the final edit or publish, call `render_asset` with `assetType=LANDING_PAGE` and the page content ID.
`manage_website_page`
Create, edit, style, publish, clone, and inspect website pages, and edit site navigation menus. Read module types and their positions before editing content. Writes are sequential. Requires user confirmation before creating a page, publishing, restoring a revision, or modifying navigation (`NAV_*` operations). After the final edit or publish, call `render_asset` with `assetType=WEBSITE_PAGE` and the page content ID. > [!NOTE] > > This tool is only available for select AI clients (Claude, ChatGPT, and Gemini).
`get_aeo_metrics`
Get brand-level AEO analytics including share of voice, prompt performance trends, and competitor comparisons. Requires Marketing Hub Professional or Enterprise.
`manage_aeo_prompts`
View tracked prompts and their performance details, including full AI engine response text from ChatGPT, Gemini, Perplexity, and Claude for any tracked prompt. Supports creating new tracked prompts. Requires Marketing Hub Professional or Enterprise.
`manage_aeo_recommendations`
Review brand recommendations and act on them, including starting content generation actions such as blog posts and social posts. Requires user confirmation before executing any action. Requires Marketing Hub Professional or Enterprise.
`render_asset`
Display a read-only preview card for a HubSpot content asset. Call this after the final edit or publish of a landing page (`assetType=LANDING_PAGE`), website page (`assetType=WEBSITE_PAGE`), or blog post (`assetType=BLOG_POST`), using the content ID returned by the tool that last modified the asset. > [!NOTE] > > This tool is only available for select AI clients (Claude, ChatGPT, and Gemini).
`manage_blog_post`
Create, update, publish, and inspect HubSpot blog posts. Supports: * Listing blogs, posts, and tags * Reading post content and metadata * Writing post body, metadata, author, and tags. New posts are created as drafts; requires user confirmation before creating * Publishing posts, which requires a description and author to already be set; requires user confirmation before publishing After the final edit or publish, call `render_asset` with `assetType=BLOG_POST` and the post content ID. > [!NOTE] > > This tool is only available for select AI clients (Claude, ChatGPT, and Gemini).
`get_social_channels`
View connected social channels and the available actions for each channel.
`read_social_posts`
View draft, scheduled, published, and failed posts in the social calendar.
`get_social_post_analytics`
View engagement and impression data for published social posts, including posts published directly on social networks.
`manage_social_posts`
Create, update, or cancel posts from your connected social media accounts.
`manage_onboarding`
Assess an account's CRM onboarding status and guide users through onboarding steps, including goal-setting and task progression.
`tool_guidance`
Retrieve usage instructions and guidance for one or more HubSpot MCP tools. Useful for understanding a tool's inputs and outputs in more depth, or learning how tools can work together.
`submit_feedback`
Send feedback about the MCP server experience to HubSpot.
## Create an MCP connector Create an MCP connector [in your HubSpot account](https://app.hubspot.com/l/mcp-auth-apps/). * 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. > [!NOTE] > > If you're including multiple redirect URLs, the first redirect URL will be used as the default redirect. ![Screenshot of the MCP connector details page in HubSpot](https://developers.hubspot.com/hubfs/Knowledge_Base_2023-24-25/developer/hubspot-mcp-connector-details-page.png) 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](#general-mcp-client-connection-instructions) section for general instructions. ## Test with the MCP inspector The [MCP Inspector](https://github.com/modelcontextprotocol/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. > [!NOTE] > > The MCP Inspector is a third-party tool maintained by the MCP community. Consult the [MCP Inspector documentation](https://github.com/modelcontextprotocol/inspector) for the most up-to-date setup instructions, as its interface is subject to change. To connect using MCP Inspector: 1. Run the [MCP Inspector](https://github.com/modelcontextprotocol/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. > [!TIP] > > Not sure where to start with MCP clients? Check out [this list](https://modelcontextprotocol.io/docs/2026-07-28/getting-started/intro) of applications that support MCP integrations. ## Troubleshooting ### PKCE-related authentication failures HubSpot's MCP server requires [PKCE](https://datatracker.ietf.org/doc/html/rfc7636) (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](https://github.com/modelcontextprotocol/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.