Scalewell / Blog

HubSpot MCP: how to connect Claude or ChatGPT to HubSpot and report paid media in pipeline

HubSpot's MCP server gives Claude and ChatGPT your deals but none of your ad spend, so here are the five connection routes and the join that reports paid media in pipeline.

A bridge linking an island of ads and spend to an island of CRM deal folders, with a small AI node aligning the pieces in the middle.

HubSpot MCP is HubSpot's official Model Context Protocol server at mcp.hubspot.com, generally available since April 13, 2026, which lets Claude, ChatGPT or any MCP client read and update your CRM. For a paid team, its real use is joining ad spend to deals. The server holds no ad spend, so that join needs a second connection.

You probably know the Monday version of this problem. The ad platforms say LinkedIn produced 140 leads at a lovely cost per lead, HubSpot says some number of deals came from "Paid social", and the two never meet until someone exports both into a spreadsheet and matches campaign names by hand. The spreadsheet is usually out of date by the time the CFO asks about it. Once an AI client handles that join, the team sees pipeline by campaign instead of leads by platform, and Scalewell makes it part of the team's week.

This guide is for the head of paid media or PPC lead who wants an AI client to do that join. It covers what the HubSpot MCP server can and can't read as of November 2026, the five routes for connecting Claude or ChatGPT to HubSpot, how to choose between them, and the exact prompt that turns spend and deals into cost per opportunity.

HubSpot runs one MCP server for CRM data and a separate one for developers

HubSpot publishes two MCP servers, and only the remote one at mcp.hubspot.com is meant for CRM data. HubSpot's changelog says the remote server "is graduating from beta and is now generally available to all HubSpot accounts", with write access added for contacts, companies, deals, tickets, line items, products and activities. Every connection uses OAuth 2.1 with PKCE, and "users can only access or modify records they already have permission to view or edit."

The second server is the Developer MCP server, which runs locally through the HubSpot CLI (version 8.2.0 or later, set up with hs mcp setup) and helps you build HubSpot apps and CMS pages in tools like Claude Code or Cursor. HubSpot's npm package, @hubspot/mcp-server, is now described on its listing as an "MCP Server for developers building HubSpot Apps", so if a guide tells you to install it and paste a private app token, you can skip that for reporting work.

Alongside the remote server, HubSpot offers two packaged apps: the HubSpot connector for Claude and the HubSpot connector for ChatGPT. They're the quickest way in, and HubSpot lists both as available on all of its products and plans.

The HubSpot MCP server reads deals and campaign attribution but no ad spend

The HubSpot MCP server gives an AI client deals, contacts, traffic source properties and closed-won campaign attribution, and nothing in its documented tool list returns ad spend. HubSpot's developer documentation lists 36 tools as of November 2026, and none of them mentions ads. That holds even though HubSpot's own ads tool stores an Amount Spent figure that, in HubSpot's words, "comes from the ad network"; no MCP tool exposes it. On the CRM side, the server reads contacts, companies, deals, tickets, leads, custom objects, activities, campaigns and marketing content, while revenue objects such as quotes, invoices and line items are read in beta. These are the tools that matter for paid reporting:

ToolWhat it does for a paid teamLimit to know
search_crm_objectsFinds deals or contacts by filters such as create date, stage or sourceUp to 5 filter groups of 6 filters, 200 results per page
query_crm_dataRuns SQL-style queries with filtering, aggregation and sortingNo joins, subqueries, association traversal or currency conversion
get_campaign_attribution_reportsReturns revenue and deal attribution for HubSpot campaigns"Scoped to closed-won deal attribution only"
read_campaign_dataReads campaign analytics, asset metrics or contact data; HubSpot points to it for all-stage deal dataDocumentation doesn't mention spend or budget
manage_crm_objectsCreates or updates records after showing a proposed-changes summaryFollows the connected user's permissions

Two of those limits shape everything that follows. The attribution tool only counts closed-won deals, so it can't tell you about open pipeline, which is the number a paid team usually needs mid-quarter. And query_crm_data can't walk from a deal to its contacts, so whatever you report on has to sit on the deal record itself.

Fortunately, it does: HubSpot's traffic source documentation says "Companies and deals associated with contacts mirror these properties", which means a deal carries an Original Traffic Source value such as Paid search or Paid social. For Paid search, Drill-Down 1 holds the campaign name from the URL's utm_campaign parameter. For Paid social, Drill-Down 1 holds the site (LinkedIn, Facebook) and Drill-Down 2 holds the utm_campaign value.

That utm_campaign value is your join key. If it matches the campaign name in Google Ads, LinkedIn Campaign Manager or Meta, an AI client can line up spend from one connection against deals from the other.

Five routes connect an AI client to HubSpot, and they differ on who holds the token

The five routes to HubSpot MCP in November 2026 are HubSpot's Claude connector, HubSpot's ChatGPT connector, the remote server through a connector you register yourself, a self-hosted open-source server, and a connector service. They read roughly the same CRM data, so the real differences are who holds the credentials, whether ad spend comes along, and whether anything can run without a chat open.

RouteReads and writesAuthenticationCost as of November 2026Ad spend in the same connection
HubSpot connector for ClaudeReads most CRM, marketing and commerce objects plus saved reports; creates and updates records; no deletes; bulk changes capped at 10 recordsOAuth through Claude's connector settingsNo HubSpot charge stated; needs a paid Claude plan (Pro, Max, Team or Enterprise)No
HubSpot connector for ChatGPTSimilar object list; creates and updates; no deletes; 10-record bulk capOAuth through ChatGPT's Apps settingsNo HubSpot charge stated; HubSpot asks only for an OpenAI accountNo
Remote server via your own MCP connectorThe full 36-tool set, scoped by the permissions granted at installOAuth 2.1 with PKCE, client ID and secret from Development, then MCP ConnectorsNo price stated in HubSpot's documentationNo
Self-hosted open-source serverWhatever the project implements; some cover contacts and companies but not dealsA HubSpot private app token you storeFree software; you run the hostingNo
Connector service (for example Windsor.ai or Zapier MCP)Windsor.ai reads HubSpot alongside ad platforms; Zapier MCP offers HubSpot actions such as Find Deal and Create DealOAuth to the vendor, which holds the HubSpot connectionWindsor.ai has a free plan, paid plans from $23 to $598 a month and quoted Enterprise pricing; Zapier MCP uses two tasks per successful callWindsor.ai yes; Zapier depends on the apps you add

A few details in that table deserve a sentence each. The Claude connector's setup page, updated October 19, 2026, says "You must have a paid Anthropic subscription" and that only one HubSpot account can be connected to a Claude account at a time. Windsor.ai's own README uses "How many HubSpot deals closed this month, and which ad spend drove them?" as an example question, and its pricing page lists MCP access on every plan. Zapier's MCP usage docs state that "Each successful tool call through your MCP server consumes two tasks." Open-source servers are independent projects, so check when each was last updated before you hand one a token: baryhuang/mcp-hubspot, one of the better known, is MIT licensed, had its last commit in November 2025, and its README lists contacts, companies and engagement data but no deal tools, which rules it out for this join.

Pick the route by where your ad spend lives

The right HubSpot MCP route depends on whether you want the spend join inside one conversation, and whether the report has to run while nobody is watching. Three questions settle it.

  1. Do you only need CRM answers in chat? Use HubSpot's packaged connector for whichever client your team already pays for. Nobody on your team has to store a token.
  2. Do you want spend and deals in the same conversation? Either add an ad-platform connection next to the HubSpot connector in the same client, or use a connector service that holds both. Claude lets you toggle each connector on or off per conversation, and our guides to the Google Ads MCP, LinkedIn Ads MCP and Meta Ads MCP cover the ad side. A connector service is simpler to set up, but it puts a third company between you and two sets of credentials.
  3. Does the report need to run on a schedule? Packaged connectors only work inside a chat someone opens. For a weekly job, register your own MCP connector for an agent, or self-host a server with a private app token and accept that your team now owns that token's security.

We'd start most paid teams on option two with HubSpot's own connector plus the ad platform they spend most on, because it answers the pipeline question this week without any hosting. If you're weighing every connection a paid team might need, MCP for marketing maps the wider set.

Connecting Claude to HubSpot takes five steps

Connecting Claude to HubSpot through the official connector follows the steps in HubSpot's knowledge base, last updated October 19, 2026. A Super Admin, or a user with App Marketplace access, has to connect first; other users need a Super Admin to approve the connector.

  1. In Claude, open your profile icon at the bottom left and go to Settings, then Connectors.
  2. Click Browse, search for HubSpot and select it.
  3. Click Connect and log in to the HubSpot account you want Claude to use.
  4. Choose which permissions to allow, then click Connect app. For reporting, allow as few write permissions as the screen lets you.
  5. Back in a Claude chat, ask a test question such as "How many deals were created last month with Original Traffic Source Paid social?" and compare the answer with a HubSpot report.

Then switch on your ad-platform connector in the same chat. If you do allow writes, set them to require approval in the connector's tool settings so Claude asks before changing a record.

ChatGPT connects through Settings, then Apps

The HubSpot connector for ChatGPT follows the same pattern, per HubSpot's ChatGPT setup page, updated September 28, 2026. Open your profile icon, go to Settings, then Apps, select HubSpot and click Connect. Log in, pick the account, choose permissions and click Connect App. HubSpot recommends that you "set Write tools to Needs Approval" in the connector's tool settings. In a chat, click the + icon, then More, and select HubSpot, or simply mention HubSpot in your prompt, which turns the connector on automatically.

To add a different MCP server to ChatGPT, such as a connector service, OpenAI's Apps SDK docs describe going to chatgpt.com/plugins, choosing "Add custom MCP server" and entering the server's public URL with its /mcp path. Account and workspace policies decide whether you can.

Claude Code and agents connect with your own MCP connector

For Claude Code, an agent framework or any MCP client that isn't Claude or ChatGPT, register a connector in HubSpot. HubSpot's developer docs give the order: create an MCP connector under Development, then MCP Connectors, with a name and redirect URL; copy the client ID and secret; point your client at https://mcp.hubspot.com; approve the OAuth screen; and run the get_user_details tool to see which tools and objects you were granted. You don't pick scopes by hand, because they follow the tools available at install and the permissions you approve.

Joining spend to deals runs on the utm_campaign value

Joining ad spend to HubSpot deals means asking each connection for the same period, grouped by the same campaign name, and dividing one by the other. The AI does the arithmetic; your job is making sure the names match before you start.

  1. Make utm_campaign equal the ad platform's campaign name. Pull a list of live campaigns from each ad account and the distinct Drill-Down values on recent deals. Every mismatch you fix now is a deal that would otherwise land in "unattributed".
  2. Ask HubSpot for deals, grouped by campaign. Filter deals created in the period with Original Traffic Source Paid search or Paid social, and return count, amount and stage by the drill-down that holds utm_campaign.
  3. Ask the ad connection for spend by campaign for the same dates.
  4. Join on campaign name and compute cost per opportunity (spend divided by deals created) and pipeline per dollar.

This prompt does all four in one go once both connectors are on:

Period: 1 to 31 October 2026.

From HubSpot: find deals created in the period whose Original Traffic Source
is Paid search or Paid social. Use search_properties first to confirm the
exact property names. For Paid search, the campaign is Drill-Down 1; for
Paid social, it is Drill-Down 2. Return, per campaign: number of deals,
total amount, and how many are past the discovery stage. Give me the total
count before any sample, and tell me how many deals had no campaign value.

From the ad platforms: spend per campaign for the same period.

Join the two on campaign name (case-insensitive, trimmed). Show a table:
campaign, platform, spend, deals, pipeline amount, cost per deal,
pipeline per dollar. List unmatched campaigns on either side separately.
Do not change anything in HubSpot or the ad accounts.

The "unmatched" list is the most useful line in the output. It tells you which campaigns are spending without a single deal attached, and which deals are being credited to campaigns nobody can find any more.

Here's what the result looks like for a hypothetical team spending $60,000 in a month across three campaigns:

CampaignSpendDeals createdCost per dealPipelinePipeline per dollar
LinkedIn, ICP job titles$30,00012$2,500$360,00012.0
Google, brand terms$10,0008$1,250$200,00020.0
Meta, retargeting$20,0002$10,000$40,0002.0

The point of the exercise is that cost per lead would have ranked these campaigns differently. For the reporting format around this table, see our guide to PPC reporting.

Two streams of data tokens, one from ad platforms and one from HubSpot deals, are matched in the middle and come out as a single table, with unmatched leftovers set aside on each side.
On the left, the ad platforms (Google Ads, LinkedIn and Meta) supply spend by campaign name. On the right, HubSpot deals supply Original Traffic Source and the utm_campaign drill-down. In the middle, the AI client matches the two on campaign name. The output is cost per deal and pipeline per dollar, plus an unmatched list on each side.

Most wrong answers come from source properties, permissions and missing tags

The HubSpot MCP join gives wrong answers for predictable reasons, and nearly all of them come from the data in HubSpot and the ad accounts.

  • Original Traffic Source is first touch. A contact who first arrived from organic search and later converted on a LinkedIn ad stays "Organic search" for good. HubSpot's own ads dashboard uses "a Last ad interaction attribution model" by default, so the two will disagree. Pick one, say which in the report, and don't let anyone compare a first-touch number with a last-touch one.
  • Some paid contacts never carry a utm_campaign. Contacts created from lead forms inside an ad platform, or from untagged links, can arrive without the drill-down your join depends on. Check how a few known lead-form contacts are tagged in your account before you trust the totals.
  • The connected user decides what the AI sees. The server only returns records that user can view. If a sales manager with a team-only view connects, the report quietly undercounts.
  • Sensitive data blocks activities. If your account has Sensitive Data turned on, calls, emails, meetings, notes and tasks are blocked from the MCP server, even though the normal CRM APIs still return them.
  • The AI may summarize a sample. Search returns 200 results per page, so ask for the total count first and check it against a HubSpot report the first few times.
  • Currency doesn't convert. query_crm_data doesn't support currency conversion, so a multi-currency pipeline needs either one currency or a conversion step you check yourself.

And if a campaign produces two or three deals a quarter, cost per deal is mostly noise. In that case report earlier-stage opportunities too, and read the trend over a longer window rather than reallocating budget on one month's figure. A paid team with very few deals per campaign may also want to look at AI lead scoring before it leans on deal counts.

Where to start

Connect HubSpot and your largest ad platform to the same AI client this week, fix the utm_campaign mismatches the first run exposes, and run the join prompt for last month before you trust it for this one. If you'd like help setting up the connections and the weekly report around them, Scalewell does that for paid teams.

Frequently asked questions

Is HubSpot MCP free?

HubSpot's documentation lists no price for the MCP server or its packaged connectors as of November 2026, and lists both connectors under all products and plans. Your costs sit elsewhere: the Claude connector needs a paid Anthropic plan, connector services charge their own fees, and all usage counts against HubSpot's normal API usage limits.

Can the HubSpot MCP server delete records?

The packaged HubSpot connectors for Claude and ChatGPT don't support deleting any object, according to HubSpot's knowledge base pages updated in September and October 2026. They can create and update records, in batches of up to 10. The developer documentation for the remote server describes a proposed-changes summary that the user reviews before any CRM record is created or updated.

Does HubSpot MCP work with Gemini or other AI clients?

HubSpot's remote server works with any MCP client that supports OAuth with PKCE, so Gemini, Cursor and agent frameworks can connect through a connector you register. HubSpot's developer docs note that a few content tools, such as the blog post and website page tools, are only available for select clients: Claude, ChatGPT and Gemini.

Can HubSpot MCP run a report on a schedule without anyone in the chat?

The packaged Claude and ChatGPT connectors only run inside a conversation someone opens. For a scheduled report, run an agent against the remote server with your own registered connector, use a self-hosted server with a private app token, or use a connector service that offers scheduled exports. Each option means someone on your team owns a stored credential.

Can I connect more than one HubSpot account?

HubSpot's Claude and ChatGPT connectors each allow one HubSpot account per AI account at a time. Agencies or teams with several portals need to disconnect and reconnect, use separate AI accounts, or register their own connector per portal on the remote server, which keeps each client's data in a separate connection.