How to connect HubSpot to your AI assistant with MCP

TL;DR

• Connect HubSpot to Claude Desktop, ChatGPT, or Cursor using Composio's MCP server without writing custom integration code.

• Composio gives your AI assistant access to 50,000+ agent-ready tools across 1,000+ business systems. HubSpot is one connection in that catalog, with OAuth token refresh, schema formatting, and credential storage handled automatically.

• The free tier includes 100,000 tool calls per month with no credit card required.

• Once connected, manage contacts, log deals, draft follow-up emails, and pull pipeline reports from a single chat prompt.

You don't need to be a software engineer to give Claude direct access to your sales pipeline. Every time you manually copy a lead's details from your inbox into HubSpot, you lose context and momentum. By routing your AI assistant through Composio's MCP gateway (the same infrastructure behind 300M+ tool calls per month across 1M+ connected accounts), you can establish a secure, two-way connection between Claude and HubSpot in a single session. Authentication, schema formatting, and token management are handled automatically, so setup doesn't become an infrastructure project.

Think of MCP as a universal connector for AI: when you type a request in plain language, the MCP server translates it into a precise HubSpot API call and hands the response back to your assistant in a format it can reason about.

Composio vs. manual HubSpot integration

Here's how the two approaches compare across the decisions that matter for a solo operator or small team.

How to connect HubSpot MCP with ChatGPT Work

Prerequisites

→ Have a ChatGPT account with access to ChatGPT Work.
→ Use the ChatGPT desktop app.
→ Have access to the HubSpot workspace you want to connect.
→ Have Composio MCP available.
→ Composio connects through OAuth, so you’ll be asked to sign in and approve permissions.

1. Open the MCP settings

→ Open ChatGPT Work.
→ Go to Settings.
→ Open the Plugins section.
→ Inside the Plugins page, click the MCP tab.

2. Add the server

→ Click Add server.
→ In the Name field, enter Composio.
→ For Type, select Streamable HTTP.
→ In the URL field, paste:

https://connect.composio.dev/mcp

→ Click Save.
→ The Composio server will now appear in your MCP plugins list.

3. Authenticate

→ Click Authenticate.
→ Log in through Composio.
→ Click Allow access to authorize ChatGPT Work to use your Composio account.

4. Start using Composio

→ Once authentication is complete, the Composio tools are available in ChatGPT Work.
→ Ask ChatGPT to work with your HubSpot account.
→ ChatGPT will run the HubSpot actions you have authorized.

Example commands

→ "Archive a batch of outdated contact records."
→ "Associate a web form with a current campaign."
→ "Add a custom data token to an event template."
→ "Archive multiple expired quotes by their IDs."

How to connect HubSpot to Claude Cowork

1. Open Customize

→ Open Claude Desktop.
→ In the left sidebar, click Customize.
→ Select Connectors.
→ Click the + icon at the top.

2. Add the Composio MCP server

→ Click Add custom connector.
→ Paste the Composio MCP server URL:

https://connect.composio.dev/mcp

→ Add the connector.

3. Authorize Composio

→ Click Connect.
→ A browser window will open.
→ Authorize Composio to continue.

4. Connect your HubSpot account

→ Go back to Claude Cowork.
→ Ask the agent to connect to HubSpot.
→ Alternatively, give Claude any HubSpot-related task.
→ Claude will prompt you to authenticate and authorize access to HubSpot.

5. Start using HubSpot

→ Complete the HubSpot authentication.
→ Composio's HubSpot tools become available in Cowork.
→ Your HubSpot account is now ready to use through Claude Cowork.

Example commands

→ “Archive a batch of outdated contact records.”
→ “Associate a web form with the current campaign.”
→ “Add a custom data token to the event template.”

→ Claude uses the connected HubSpot tools to perform the requested action.

How to connect HubSpot MCP with Cursor

1. Install Composio in Cursor

→ Open Cursor.
→ Use the Install in Cursor option on the Composio page.
→ This adds Composio to Cursor automatically.

2. Add Composio manually

Note: This path requires editing a JSON config file. If you're not comfortable with that, use the one-click Install in Cursor option in step 1 and skip to step 3.

→ Open .cursor/mcp.json in your project root.
→ For a global configuration, open ~/.cursor/mcp.json instead.
→ Add this configuration:

{
  "servers": {
    "composio": {
      "type": "http",
      "url": "https://connect.composio.dev/mcp"
    }
  }
}

→ Save the file.

3. Restart Cursor

→ Restart Cursor.
→ Open the MCP Tools settings.
→ Find Composio.
→ Click Connect next to Composio.

4. Authorize Composio

→ A browser window will open.
→ Follow the authorization flow.
→ Approve the requested access.
→ Return to Cursor after authorization is complete.

5. Connect your HubSpot account

→ Go back to Cursor.
→ Ask the Cursor agent to connect to HubSpot.
→ Or give it any HubSpot-related task.
→ Cursor will prompt you to authenticate and authorize access to HubSpot.

6. Start using HubSpot

→ Complete the HubSpot authentication.
→ Composio's HubSpot tools are now available in Cursor.
→ Your HubSpot account is ready to use through Cursor.

Example commands

→ “Archive a batch of outdated contact records.”
→ “Associate a web form with the current campaign.”
→ “Add a custom data token to the event template.”
→ Cursor can then use the connected HubSpot tools to perform the requested actions.

7. One-click vs. manual setup

→ One-click: Click Install in Cursor → authorize → connect HubSpot.
→ Manual: Edit .cursor/mcp.json → add the Composio server → restart Cursor → click Connect → authorize → connect HubSpot.

Configuring HubSpot permissions

HubSpot publishes a defined set of OAuth 2.0 scopes that control what data your connection can access. Each scope restricts access to specific parts of your CRM. Granting the minimum necessary scopes protects sensitive CRM data while giving your AI assistant exactly what it needs to execute tasks.

Composio's documentation explains how to configure which HubSpot scopes and actions are allowed when connecting your account. You can also use the API to query required scopes before connecting.

Essential permissions for CRM tasks

For a solo consultant managing a personal pipeline, the minimum viable scope set is:

• crm.objects.contacts.read and crm.objects.contacts.write

• crm.objects.deals.read and crm.objects.deals.write

Updating your HubSpot permissions

If your workflow changes and you need additional scopes, update them through the Composio dashboard and then re-authorize the HubSpot connection. The new scopes take effect after the next authorization flow completes, and you don't need to reinstall anything.

Practical use cases for your MCP connection

Managing HubSpot MCP contact lists

Once you have write access to contacts, you can create contact records directly from a prompt:

"Add John Doe (john@example.com) to my HubSpot contacts and tag him as a warm lead."

The Composio HubSpot toolkit handles the structured API call, creates the contact record with the email address as the primary identifier, and confirms the creation in the chat response. No tab-switching required.

HubSpot MCP for real-time deal logs

The deal retrieval and creation tools let you manage deals in HubSpot:

"Log a new deal for Acme Corp valued at $5,000 in the Discovery stage."

The tool creates the deal record, associates it with the Acme Corp company object if it exists, and returns the deal ID and a confirmation. You can chain this into a follow-up prompt to immediately schedule a task.

Syncing HubSpot data into emails

Because the MCP connection gives Claude direct access to your CRM's contact history and associated properties, you can use stored context to draft outreach without copy-pasting:

"Draft a follow-up email to Jane Smith using the context from our last HubSpot note."

Claude pulls the most recent activity from Jane Smith's contact record and drafts a relevant email in your preferred tone, so you never start from a blank message.

Retrieving deal reports from HubSpot

"Summarize all deals closing this month and calculate the total pipeline value."

This prompt calls the deals retrieval tool with a date filter and aggregates the results into a summary. The output that previously required opening HubSpot reports, exporting data, and running a sum in a spreadsheet now happens in one prompt.

Fixing common HubSpot MCP integration errors

Fixing expired access tokens

Note: The command below is for technical users who want to verify connection status from the terminal. If you're not using the CLI, check connection status from your Composio dashboard instead.

Composio refreshes HubSpot OAuth tokens automatically before the 30-minute expiry window closes. If a connection enters an EXPIRED state after the refresh token is revoked or expires, you must re-authenticate through a fresh Connect Link by signing in again through Composio. You can confirm the current connection status at any time by running composio connected-accounts list --toolkits hubspot.

Granting HubSpot API access scopes

If your AI assistant returns a "Missing Scope" error when attempting a specific action, the connected account does not have the required permission for that tool. Resolve this by logging into your Composio dashboard, navigating to Connected Accounts > HubSpot, clicking Manage Scopes, and selecting the required permission. Then re-authorize the connection.

Fixing unstable local MCP connections

Local MCP servers depend on your machine being powered on. If you want a connection that stays active regardless of your local machine status, switch to Composio's hosted remote MCP server: open your Claude Desktop config file, set the url value to the Composio hosted gateway endpoint, save, and restart Claude. This moves the infrastructure off your laptop entirely and is the recommended path for daily production use.

Resolving setup roadblocks for HubSpot MCP

HubSpot free account limitations

HubSpot caps free and Starter plan accounts at 100 requests per 10 seconds and 250,000 API calls per day. Professional accounts get 190 requests per 10 seconds and up to 625,000 daily calls. Enterprise accounts get the same rate limit with up to 1,000,000 daily calls, per HubSpot's API usage documentation. For a solo operator running a personal CRM, these limits typically accommodate regular conversational workflows. If you run automated batch workflows that scan large contact lists, be aware of the daily cap.

Multi-AI support for HubSpot MCP

One Composio connection serves Claude, ChatGPT, and Cursor simultaneously. Configure the connection once through the CLI or dashboard, then add the same MCP server URL to each client's settings. Composio handles the credential storage and token refresh for all three.

Building and maintaining a custom HubSpot integration typically takes two to three months from kickoff to completion for most mid-market projects, and that timeline doesn't include ongoing maintenance when HubSpot updates its API. Composio absorbs those deprecations and versioning changes, so you ship the connection once and move on.

Composio's flat-tier pricing covers all three clients under one connection, with no additional setup required per client.

Managing HubSpot API permissions

To revoke Composio's access to HubSpot, open your HubSpot account settings, navigate to Integrations > Connected Apps, find Composio in the list, click Actions, and then click Uninstall. This revokes the OAuth grant at the HubSpot level.

The same fast-setup pattern applies to HubSpot as it does to any integration in the Composio catalog.

Setup takes a single session. Once the MCP server URL is saved and HubSpot is authorized, every client you add reads from the same connection, with no reinstall and no additional configuration.

Create a free Composio account, connect HubSpot with your chosen AI assistant, and run your first prompt. The free tier gives you 100,000 tool calls per month with no credit card required.

FAQs

Can I use this integration on HubSpot's free plan?

Yes, the integration works with HubSpot's free tier. You must stay within HubSpot's rate limit of 100 requests per 10 seconds and 250,000 calls per day, which is rarely a constraint for individual operators running conversational workflows.

What happens when my HubSpot access token expires?

Composio's managed auth layer handles the OAuth 2.0 token refresh cycle automatically. You don't need to re-authenticate mid-conversation.

Does one Composio account work with Claude, ChatGPT, and Cursor simultaneously?

Yes. One connected HubSpot account in Composio serves all three clients. Add the same MCP server URL to each client's configuration and they all read from the same authenticated connection.

How much does it cost to run this in production?

Composio's free tier includes 100,000 tool calls per month with no credit card required. The Pro plan at $29 per month adds 50,000 tool calls, enough headroom for daily contact management, deal logging, and pipeline queries across a full working month.

Key terms glossary

Model Context Protocol (MCP): A system that allows AI assistants to securely read data and execute actions across connected applications by exposing structured tool definitions through a standardized interface.

Tool schema: A structured definition that tells an AI model exactly what inputs a given tool expects, what data it returns, and how to format the request correctly.

In-chat auth: A secure authentication flow where an AI assistant generates a temporary Connect Link URL mid-conversation, allowing the user to authorize access to an external service without leaving the chat.

OAuth 2.0 token refresh: The process of exchanging an expiring access token for a new one using a stored refresh token, keeping an API connection ACTIVE without requiring the user to re-authenticate.

MCP gateway: A centralized server that exposes multiple tool integrations through a single MCP-compatible URL, so any MCP client can connect without additional configuration per integration.