TL;DR
To connect HubSpot to Claude via MCP: copy mcp.portermetrics.com/mcp, go to Claude.ai, open Connectors → Manage connectors → Add custom connector, paste the URL, and sign in. From there, ask Claude anything about your HubSpot CRM data in plain English.
Once connected, you can automate your HubSpot reporting and analysis — ask questions about your data, build dashboards, trigger alerts, or ship client-ready reports like the one below.
Prerequisites
- A Porter Metrics account with your HubSpot account connected (free tier is enough to try it end-to-end)
- A Claude account — the free plan works for Claude Web; a Pro subscription is needed for Claude Code and Desktop MCP features
- Admin or standard access to the HubSpot accounts you want to connect
Connect HubSpot to Claude with MCP
For this tutorial we’re going with the MCP method. Here’s a quick explainer of what MCP is and why it’s the best path for HubSpot.
MCP (Model Context Protocol) is the open standard that lets AI tools like Claude, ChatGPT, Claude Code and others access and use external APIs — the things that make tools like HubSpot work under the hood. Instead of building a custom integration for every AI tool you use, you install one MCP and every compatible AI gets access to the same data.
The full setup takes under 5 minutes and breaks into three moves: connect HubSpot to Porter, point Claude at the Porter MCP, and ask your first question.
1. Connect your HubSpot data to Porter
Porter sits between HubSpot’s CRM API and Claude. It handles OAuth, rate limiting, pagination and all the plumbing so Claude only ever sees clean, structured data.
Sign up for Porter. Create a free account at portermetrics.com. The free tier is enough to run this full workflow end-to-end.
Connect your HubSpot account. In Porter, click Create → pick Claude as the destination → select HubSpot as the source → sign in with HubSpot to grant access to your accounts.
Select your accounts. Choose the HubSpot accounts you want Claude to query. When you select multiple accounts under a single connection, Porter automatically blends their data together so you can query them as one.
Optional: enable automatic BigQuery storage if you’re connecting multiple accounts with large data volumes. This keeps Claude’s responses fast even at scale.
2. Connect the MCP to Claude
Porter’s MCP URL is what you paste into Claude. Once added, Claude can query HubSpot data on demand in any conversation.
Go to claude.ai and click the + icon in the chat input to open the tools menu.
In the menu that opens, hover over Connectors and click Manage connectors.
In the Connectors panel, click the + button at the top of the list to start adding a new connector.
Pick Add custom connector from the dropdown that appears.
A dialog opens with the name and URL fields. Type Porter in the first field to name the connector.
In the second field, paste https://mcp.portermetrics.com/mcp. Leave the advanced settings alone.
Click Add at the bottom right of the dialog. Claude opens a sign-in window — use the same Google account linked to your Porter workspace and approve access.
Once the authorization finishes, you’ll see Porter’s read-only tools appear in the connectors panel. You’re ready to start asking questions.
For a fuller walkthrough with screenshots at every step, see the Porter MCP tutorial.
3. Start building questions and dashboards
With Porter connected, open a new Claude chat and ask anything about your HubSpot in plain English. Claude calls Porter behind the scenes, pulls live data from HubSpot, and answers with tables, charts, or summaries.
Try one of these to verify the setup is working:
For a full catalogue of copy-paste prompts organized by use case (agencies, B2B marketers, sales-led teams, cross-channel), jump to the prompts section below.
Alternative ways to connect HubSpot to Claude
MCP is the path we just walked through — and the one we recommend for most marketers. But it’s not the only way to get HubSpot data in front of Claude. The most common alternatives are HubSpot’s direct API (or its official MCP if it has one), a live Google Sheets bridge, and BigQuery for scale. Each has its trade-offs — pick the one that fits how your team already works.
- 🔌 HubSpot’s direct API (or official MCP) — Talk to HubSpot’s CRM API yourself, or install the official HubSpot MCP if one exists. Maximum control, but you handle auth, rate limits and pagination — and you only get one source.
- 📊 Google Sheets — Live Sheet or one-off CSV upload. Auditable, familiar, faster for big exports — but aggregation happens in the Sheet, not the API.
- 🗄️ Google BigQuery — For large accounts or agencies running multi-account analysis. BigQuery aggregates; Claude only queries pre-built summaries.
Via HubSpot’s direct API (or official MCP)
If you’re building a product around HubSpot — or you’re a developer who’d rather own every layer of the integration — the most direct path is talking to HubSpot’s CRM API yourself, or installing the official HubSpot MCP. HubSpot ships both an official Native Connector for Claude and an official MCP Server. The Native Connector is the easiest path for most users; the MCP Server gives developers more control. You’ll need to follow HubSpot’s rate limits & quotas and request a Developer Token / API access where applicable. Either way, you skip Porter entirely and call HubSpot from your own code or from Claude Code with raw HTTP requests.
Via Google Sheets (live Sheet or manual CSV)
If your team already lives in Google Sheets — or you want a paper trail before Claude touches anything — feed HubSpot into a Sheet, then let Claude read the Sheet. You can automate the HubSpot → Sheets pipeline with Porter so it refreshes daily, or do one-off CSV exports from HubSpot’s native UI for static analysis.
Read the full Sheets tutorial →
Via Google BigQuery (for scale)
This is the path most people overlook — and it’s the one that saves you when your HubSpot account gets serious. A single large user or an agency managing 10+ accounts will hit API rate limits and latency problems querying Claude directly. Claude will literally tell you it’s taking too long or timing out on big pulls.
BigQuery fixes that. You load HubSpot data into BigQuery tables on a schedule, then connect BigQuery to Claude — either through a BigQuery MCP or via Claude Code with SQL queries. Instead of asking Claude to pull raw HubSpot data, you let BigQuery aggregate into small, optimized tables, and Claude only queries the summarized output. Scale problem solved.
Read the full BigQuery tutorial →
Connecting HubSpot to Claude Code
Most marketers lump Claude and Claude Code together and miss the biggest advantage of the entire MCP ecosystem. They’re not the same tool — and the difference matters enormously once you start working with HubSpot data seriously.
Claude is a chat interface. You ask a question, Claude pulls live data through the MCP, answers, maybe builds a quick dashboard inside the conversation. Great for one-off analysis. The problem: everything is ephemeral. Want to refresh the dashboard tomorrow? You regenerate it from scratch. Want the same report every Monday? You re-ask the question every Monday.
Claude Code is Claude running inside your computer’s terminal. Because it has access to your filesystem, runtime, and other developer tools, it doesn’t just answer questions — it can build real software. Persistent scripts, scheduled routines, HTML apps, internal dashboards, integrations that run 24/7 without your input. Once it’s connected to Porter’s MCP for HubSpot, a whole category of work becomes possible.
What Claude Code unlocks that Claude alone cannot
This is where the MCP ecosystem pays off most. Because Claude Code can combine Porter’s MCP with other MCPs — Firecrawl for web scraping, Airtable for structured data, Notion for wikis, Vercel for deployment, Slack and Gmail for delivery — you’re no longer querying data. You’re building tools.
🛠️ Build your own CRM dashboard
Stack: Porter MCP + Vercel MCP (or Cloudflare Pages, Netlify)
Feed Claude Code your HubSpot pipeline targets, deal values, and close rates — and ask it to generate a custom pipeline dashboard for each client. It builds the HTML, pulls live data, deploys to a URL. No static spreadsheet embed to break when the vendor changes pricing, no template constraints. The dashboard updates automatically because it queries Porter’s MCP on every page load.
Best for: agencies that want white-label client dashboards without Looker or Data Studio dependencies.
🔍 Full competitor + performance monitoring
Stack: Porter MCP + Firecrawl MCP
Combine your own HubSpot performance from Porter with competitor CRM strategies and market positioning scraped via Firecrawl. Claude Code stitches both into a weekly competitive intelligence report — your numbers next to their pipeline velocity and deal sizes, with an LLM summary on top of what changed week over week. Runs on cron, lands in your inbox every Monday morning.
Best for: in-house teams that need market context, not just internal numbers.
📚 Internal marketing wiki with live metrics
Stack: Porter MCP + Airtable MCP (or Notion MCP)
Use Airtable or Notion as the schema, Porter as the data source. Claude Code keeps every page populated with current deal amount, deal probability, and contact lifecycle stage for every account — no stale screenshots, no copy-paste from Excel. New hires read one wiki entry and have full context on a client’s account.
Best for: agencies and ops teams onboarding analysts or rotating account managers frequently.
🔔 24/7 alerts on pipeline health, deal stagnation, and contact inactivity
Stack: Porter MCP + Slack MCP (or Gmail MCP)
A Claude Code routine on cron pulls HubSpot via Porter, evaluates thresholds — deal probability drops below 20%, no activity on high-value deals for 14+ days — and pushes Slack or Gmail alerts the moment something crosses the line. You stop checking dashboards reactively; the dashboard checks itself and tells you when to look.
Best for: any team that’s ever discovered a problem 48 hours too late because nobody opened the report.
Bottom line: Claude is for quick questions and ad-hoc dashboards. Claude Code is for building apps, live dashboards, alerts, and actual tools — anything you want to run on its own without re-asking. Same Porter MCP URL works in both, so you don’t pick once and lock in.
Use cases — what you can actually do once HubSpot is connected to Claude
Getting the connection right is half the battle. The real value shows up in what you do next. Here are the use cases Porter users build around their HubSpot data — from simple Q&A to full client-facing workflows.
1. Chat and ask questions directly
The simplest use case — and still the one 80% of marketers start with. Open Claude, ask a question, get an answer grounded in live data.
It’s the fastest way to replace a daily HubSpot dashboard check-in. But chat is table stakes — the interesting use cases come next.
2. Blend HubSpot with your revenue data (Meta Ads, Google Ads, LinkedIn Ads)
This is where a 360° view gets real. When you connect HubSpot and your revenue source (Meta Ads for lead gen, Google Ads for paid search, LinkedIn Ads for B2B prospecting), Claude can map deals and contacts to actual closed-won deals — using contact source, campaign names, and timestamps — and give you attribution that no platform-side number can.
Claude handles the contact source, campaign names, and timestamps mapping and joins. You get a client-ready attribution report that no single platform can generate on its own.
3. Automated alerts and notifications on Slack or Gmail
With Claude Code you can turn HubSpot monitoring into a routine that runs on its own. Hook Porter’s MCP (for the data) together with a Slack or Gmail MCP (for delivery), then write a Claude Code scheduled task that pulls performance every morning and pings you only when something actually needs attention.
No dashboards, no daily check-ins. The report comes to you — and only when it matters.
4. Client-ready presentations with live data (Gamma, HTML, PDF)
A common agency pain: you send clients a static HubSpot report that exports break when filters change — and you spend an hour explaining a broken dashboard. With Claude you can build the presentation itself — as a Gamma deck, a custom HTML page, or a PDF — populated with live numbers each time.
The presentation becomes a delivery artifact you send to the client, not a dashboard that depends on another tool staying up. No broken iframe, no login prompts, just the content.
HubSpot fields and metrics you can query with Claude
Before you start writing prompts, it helps to know what data is actually available. Porter MCP gives Claude access to 510 HubSpot fields and metrics across every reporting level, plus breakdowns by contact, company, deal, and engagement dimensions. And the same MCP URL also unlocks 25+ other sources — so Claude can blend HubSpot with Google Ads, GA4, Shopify and more in a single prompt.
See All HubSpot fields and metrics for the complete reference.
Prompts you can copy-paste today
1. For agencies
Use these when managing multiple client HubSpot accounts or building white-label reports.
2. For B2B marketers
Use these for campaign performance, lead nurturing, and funnel analysis.
3. For sales-led teams
Use these for pipeline health, deal forecasting, and sales activity tracking.
4. Cross-channel
Use these when HubSpot is connected alongside other data sources through Porter MCP.
Limits, auth, and best practices for HubSpot via Claude
This is the most common “horror story” pattern for HubSpot API users: not bans, but silent partial failures at scale. Because HubSpot returns HTTP 429 (throttle) errors rather than halting the entire pipeline, ETL jobs and automation scripts often continue with incomplete data. A marketer running a bulk contact enrichment via Claude MCP who doesn’t check response codes can end up with a CRM where 40% of records have updated lifecycle stages and 60% don’t — making segmentation and reporting unreliable. The cost isn’t account suspension; it’s decisions made on dirty data.
HubSpot’s rate-limit enforcement is quota-based and rolling-window, not tool-based. HubSpot doesn’t ban or suspend accounts because you used Claude, an MCP server, or a third-party integration. It throttles requests because of how the API was used: exceeding burst limits (requests per 10-second window), exceeding daily quotas (rolling 24-hour totals), or hitting per-endpoint caps like the Search API’s 4 requests/second limit. Read-only usage within your tier’s quota is safe. Bursty parallel writes, unbatched bulk operations, and unscoped API keys are not. When a limit is hit, HubSpot returns HTTP 429 with a Retry-After header; requests resume automatically once the rolling window refills. There is no permanent “strike” system or account-level penalty.
What actually goes wrong when scaling HubSpot via Claude
After reviewing official docs and community threads, two patterns come up again and again.
1. Parallel API bursts and unbatched bulk writes. Sending concurrent requests or large unbatched payloads violates HubSpot’s token-bucket burst limits (100 requests per 10 seconds on Free/Starter, 190 on Professional, 200 on Enterprise). When exceeded, HubSpot returns HTTP 429 and blocks further requests until the bucket refills. If your Claude MCP tool or automation script doesn’t handle 429s with exponential backoff, the pipeline continues with partial data — creating an inconsistent CRM. Official docs: HubSpot API Usage Limits via Reform.app rate limit guide. What to do instead: batch writes to 100 records per request max and implement exponential backoff starting at 1 second, doubling up to 16 seconds.
2. Exposing API keys or access tokens in shared environments. A 2024 security audit found that 1.6 million HubSpot users’ data was compromised through exposed API keys in public repositories, browser extensions, and shared Claude Desktop configurations. Unlike OAuth-based Native Connectors (which use scoped, rotating tokens), MCP Server setups and Private Apps rely on static access tokens that can be leaked in JSON config files, GitHub gists, or team-shared Claude Desktop settings. Source: BeVigil security research. What to do instead: use the Native OAuth Connector when possible; if using MCP Server, store tokens in environment variables or a secrets manager, never in committed JSON files.
3. Over-privileged scopes and ignoring validation bypasses. The HubSpot Native Connector for Claude requests broad read/write scopes at setup. If configured before November 20, 2025, it may lack write permissions and require a full disconnect/reconnect to enable record creation — a disruption that breaks automated workflows. More critically, custom validation rules configured in HubSpot are NOT applied when creating or updating records via the API or connector, meaning Claude can write data that violates your CRM’s own data-quality rules (e.g., invalid email formats, missing required fields, duplicate company names). Source: HubSpot Knowledge Base — Best Practices and developers.hubspot.com/mcp. What to do instead: audit scopes after setup, reconnect if write permissions are missing, and run validation reports in HubSpot UI after any bulk Claude-initiated update.
Both behaviors trigger quota-based throttling and data quality degradation. If you want to use Claude for HubSpot safely, use Porter’s managed MCP which handles batching, backoff, and OAuth rotation automatically.
The 5-rule best-practice protocol
Based on HubSpot’s documented rate limits and quotas and the behaviors that have actually caused silent partial failures — not guesswork:
- Stay under your tier’s burst limit. Free and Starter HubSpot accounts are capped at 100 API requests per 10-second window; Professional at 190; Enterprise at 200. Exceeding this triggers HTTP 429 and pauses your pipeline. . Consequence if ignored: mid-sync throttling leaves your CRM in a partially updated state. Porter enforcement: Porter MCP batches all HubSpot requests and enforces per-10-second rate pacing automatically.
- Batch bulk operations to 100 records per request. HubSpot’s bulk endpoints accept up to 100 records per batch. The Native Connector for Claude has a stricter limit of 10 records maximum per create/update operation. Sending larger payloads results in rejected records or split transactions. Source: HubSpot Knowledge Base (Native Connector table) and HubSpot API docs. Consequence if ignored: records silently fail or require manual re-entry. Porter enforcement: Porter splits bulk requests into 100-record chunks and surfaces failed records in the response.
- Implement exponential backoff on 429 errors. When HubSpot throttles, it returns HTTP 429 with a
Retry-Afterheader. Best practice is to wait 1 second on the first 429, then double the wait time (2s, 4s, 8s, 16s) up to a maximum of 16 seconds before retrying. Source: HubSpot Developer Docs via Consultevo rate limit guide. Consequence if ignored: retrying immediately extends the throttle window and can compound partial-failure states. Porter enforcement: Porter MCP includes automatic exponential backoff with jitter on all 429 responses.
- Monitor your daily quota, not just burst limits. Free/Starter accounts have a 250,000-request rolling 24-hour quota; Professional 650,000; Enterprise 1,000,000; Public apps 500,000. A large historical sync or backfill can burn the entire daily quota by noon, leaving evening automations stalled. Source: Reform.app rate limit guide and Consultevo guide. Consequence if ignored: scheduled workflows (email sends, lead scoring, reporting refreshes) fail for hours. Porter enforcement: Porter tracks per-account daily quota consumption and warns when 80% is reached.
- Never commit API tokens to shared files or repositories. HubSpot Private App tokens and legacy API keys are static credentials. A 2024 audit found 1.6 million users’ data exposed through leaked keys in public code repositories. If using the MCP Server path with Claude Desktop, store the
accessTokenin environment variables or a secrets manager — never inclaude_desktop_config.jsonthat gets shared via Slack, Notion, or GitHub. Source: BeVigil security research. Consequence if ignored: unauthorized access to your entire CRM, including contacts, deals, revenue data, and engagement history. Porter enforcement: Porter’s managed MCP uses OAuth token rotation and never exposes static credentials to end users.
What Porter MCP does differently: it enforces these limits and safeguards at the platform level. Porter’s HubSpot MCP batches requests into HubSpot-compliant chunks (max 100 records per batch), enforces per-tier burst pacing (100/190/200 per 10s), implements automatic exponential backoff with jitter on 429 responses, and tracks daily quota consumption across all connected accounts. Unlike self-hosted MCP servers where rate-limit logic is the user’s responsibility, Porter handles token rotation via OAuth (no static keys in JSON files), minimizes scopes to read-only by default, and surfaces validation warnings when HubSpot custom rules would be bypassed. That’s the behavior HubSpot’s automated systems handle gracefully — no throttling, no partial syncs, no exposed credentials.
Frequently asked questions
A HubSpot MCP (Model Context Protocol) is an open standard that lets AI tools — Claude, Claude Code, ChatGPT, Cursor — connect to your HubSpot data without custom integrations. Porter’s MCP server makes your deals, contacts, and companies available through one URL: no tokens, no scripts, no developer setup.
Claude is the conversational product (web, app, mobile). Claude Code is a terminal-based developer tool that can write scripts, save files, and automate workflows. Both can connect to HubSpot via MCP.
HubSpot’s API refreshes on a rolling window . Porter MCP pulls live, so your data is always within that window.
Yes. HubSpot enforces tiered burst limits: 100 requests per 10 seconds on Free/Starter, 190 on Professional, and 200 on Enterprise, plus daily quotas up to 1,000,000 requests. Porter MCP batches requests into 100-record chunks and enforces per-tier pacing automatically. Source: [HubSpot API Usage Details]
Two common reasons: (1) Refresh lag — HubSpot reporting data updates on a rolling window, so API pulls may lag behind the UI. (2) Partial sync — throttled or bulk operations can leave records half-updated if 429 errors aren’t handled. The fix: test with a small date range first and verify record counts match. Source: [HubSpot Knowledge Base, HubSpot API Usage Details]
No. HubSpot doesn’t ban or restrict accounts for legitimate API usage, and Porter MCP is read-only by default — it stays well inside HubSpot’s normal rate limits. The thing to watch is rate throttling causing silent partial failures at scale — see the limits section above. Source: [HubSpot API Usage Details, HubSpot Community Forums]
Ready to chat with your HubSpot?
Open Claude, add the Porter connector, and ask your first question. If you don’t have Porter yet, start a free trial and connect your HubSpot account — you’ll be chatting with your deals, contacts, and companies in under five minutes.
rocket_launchStart free Porter trialopen_in_newOpen Claude