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.

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:
| Tool | What it does for a paid team | Limit to know |
|---|---|---|
search_crm_objects | Finds deals or contacts by filters such as create date, stage or source | Up to 5 filter groups of 6 filters, 200 results per page |
query_crm_data | Runs SQL-style queries with filtering, aggregation and sorting | No joins, subqueries, association traversal or currency conversion |
get_campaign_attribution_reports | Returns revenue and deal attribution for HubSpot campaigns | "Scoped to closed-won deal attribution only" |
read_campaign_data | Reads campaign analytics, asset metrics or contact data; HubSpot points to it for all-stage deal data | Documentation doesn't mention spend or budget |
manage_crm_objects | Creates or updates records after showing a proposed-changes summary | Follows 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.
| Route | Reads and writes | Authentication | Cost as of November 2026 | Ad spend in the same connection |
|---|---|---|---|---|
| HubSpot connector for Claude | Reads most CRM, marketing and commerce objects plus saved reports; creates and updates records; no deletes; bulk changes capped at 10 records | OAuth through Claude's connector settings | No HubSpot charge stated; needs a paid Claude plan (Pro, Max, Team or Enterprise) | No |
| HubSpot connector for ChatGPT | Similar object list; creates and updates; no deletes; 10-record bulk cap | OAuth through ChatGPT's Apps settings | No HubSpot charge stated; HubSpot asks only for an OpenAI account | No |
| Remote server via your own MCP connector | The full 36-tool set, scoped by the permissions granted at install | OAuth 2.1 with PKCE, client ID and secret from Development, then MCP Connectors | No price stated in HubSpot's documentation | No |
| Self-hosted open-source server | Whatever the project implements; some cover contacts and companies but not deals | A HubSpot private app token you store | Free software; you run the hosting | No |
| 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 Deal | OAuth to the vendor, which holds the HubSpot connection | Windsor.ai has a free plan, paid plans from $23 to $598 a month and quoted Enterprise pricing; Zapier MCP uses two tasks per successful call | Windsor.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.
- 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.
- 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.
- 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.
- In Claude, open your profile icon at the bottom left and go to Settings, then Connectors.
- Click Browse, search for HubSpot and select it.
- Click Connect and log in to the HubSpot account you want Claude to use.
- Choose which permissions to allow, then click Connect app. For reporting, allow as few write permissions as the screen lets you.
- 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.
- Make
utm_campaignequal 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". - 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. - Ask the ad connection for spend by campaign for the same dates.
- 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:
| Campaign | Spend | Deals created | Cost per deal | Pipeline | Pipeline per dollar |
|---|---|---|---|---|---|
| LinkedIn, ICP job titles | $30,000 | 12 | $2,500 | $360,000 | 12.0 |
| Google, brand terms | $10,000 | 8 | $1,250 | $200,000 | 20.0 |
| Meta, retargeting | $20,000 | 2 | $10,000 | $40,000 | 2.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.

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