Query HubSpot CRM with Claude or Cursor via the HubSpot MCP server.
A 5-minute hubspot mcp setup that lets your AI tool ask plain-English questions about your contacts, companies, deals, tickets, and custom objects. The Query Streams agent caches the HubSpot CRM API into a local DuckDB SQL surface, so the LLM sees real tables — with multi-object joins, schema-aware enums, and per-pipeline deal-stage discovery — instead of REST endpoints. A different model from HubSpot Breeze AI’s UI-bound assistant.
Ask Nova, get SQL + charts
Meet Nova
One key per partner. No credentials shared.
Build an API
+more
Scheduled sync to 6+ platforms
Explore
+more
Query APIs with SQL, no code
Explore
+more
Claude, Cursor, ChatGPT & Grok talk to your data
Connect AIQuery Streams is a secure, real-time data integration platform that brings every database and SaaS API in your account into Claude, Cursor, ChatGPT, and Grok — through a single MCP key with no firewall changes. This guide walks through the hubspot mcp path specifically, so your AI tool can answer plain-English questions about contacts, companies, deals, tickets, and custom objects without you exporting CSVs out of HubSpot or wrestling with the v3 REST API. The Network Agent pulls HubSpot CRM data into a local DuckDB cache, so the LLM sees clean SQL surfaces (contacts, companies, deals, tickets, owners, custom objects) instead of REST envelopes — and Schema Intelligence handles HubSpot’s idioms (per-pipeline dealstage enums, hs_object_id string joins, lifecyclestage enums, custom-object property flattening) so the SQL is right on the first try. Learn more at QueryStreams.com and sign up for free to start asking your AI tool real HubSpot CRM questions.
What the Query Streams HubSpot MCP server gives you
Other “HubSpot MCP” servers on the open-source landscape connect the AI tool directly to the HubSpot v3 REST API and push raw object-by-object calls at it. That works, but it pushes a HubSpot private-app token into your AI client’s config, leaves the LLM staring at REST resources and property selectors instead of SQL, scopes the AI tool to only HubSpot, and gives you no audit trail of what the AI actually asked. The Query Streams hubspot mcp server solves a wider problem: one key, every connector, full audit trail, the agent normalises HubSpot CRM data into multi-object joinable SQL surfaces, and the AI tool never holds your HubSpot credentials.
Zero inbound firewall holes
The Network Agent opens a single outbound encrypted cloud link to Query Streams. Your AI client connects to the cloud, never to your HubSpot private-app token or your network. No port to open, no IP to allowlist, no VPN.
One key, every connector
The same MCP key reaches HubSpot alongside every other database and SaaS API your account has connected. Add a Stripe or PostgreSQL connector tomorrow and the AI tool sees it next to your CRM — and joins HubSpot deals to Stripe charges in a single SELECT — without re-keying.
Schema Intelligence baked in
The AI sees AI-curated descriptions, semantic types (currency, email, lifecycle stage, per-pipeline deal-stage enums), sample values, and discovered foreign keys for every HubSpot property — not just snake_case property names. It writes accurate SQL the first try, including the multi-pipeline-aware dealstage IN (...) filters that bare-schema LLMs miss.
Read-only enforced at the agent
Even a hallucinating LLM can’t update a contact, change a deal stage, or delete a company through Query Streams MCP. The Network Agent rejects anything that isn’t SELECT, WITH, or EXPLAIN before it reaches the cached HubSpot tables — and HubSpot mutate operations are never exposed to the MCP surface in the first place.
Per-key rate limits
Default 60 requests per minute and 10 execute calls per minute, configurable per key. A runaway AI tool-call loop hits a token bucket, not your HubSpot daily API quota, your private-app rate limit, or your wallet.
How it works without opening firewall ports
The Query Streams Network Agent is a small program you install once on a machine with internet access (any laptop, server, or cloud VM — the HubSpot API is reachable from anywhere). It opens one outbound TLS cloud link to the Query Streams cloud and waits there for tool calls. When Claude or Cursor asks a question, the cloud forwards the request to the agent, the agent calls the HubSpot v3 REST API, the agent caches the response in a local DuckDB so the AI sees clean SQL surfaces — contacts, companies, deals, tickets, owners, pipelines, plus every custom object you’ve configured — instead of REST envelopes, and the result streams back through the same outbound channel. Nothing inbound. Nothing exposed. The AI tool never sees your HubSpot private-app token, your hub ID, or your OAuth refresh token.
AI Client
Cursor, Claude,
ChatGPT, Grok
QS MCP Server
Streamable HTTP
X-MCP-Key auth
Network Agent
On your network
Cloud link out
HubSpot CRM API
read-only
DuckDB cache
The MCP key you give Cursor or Claude is scoped (read / analyze / execute), revocable at any time, and rate-limited per-key. The AI tool calls these MCP tools to do its work:
pattern_key with optional parameter overrides.Why Schema Intelligence makes Query Streams MCP different
Most “MCP for HubSpot” servers in the open-source landscape hand your AI tool the same v3 property reference HubSpot publishes for developers — or worse, the raw information_schema of whatever cache they keep. Property names. Data types. Maybe a primary key. The LLM is left to guess that dealstage is enum-valued and the enum values vary per pipeline, that hs_object_id is a STRING (not numeric) so joins need string comparison, that lifecyclestage on contacts spells differently than a similarly-named column on deals, or that custom-object properties live behind API ids like 2_id__property_name that need flattening before SQL can touch them. That’s why the first SQL most LLMs write against a bare HubSpot schema is wrong — not because the LLM is bad, but because it doesn’t have the data it needs to be right (and a per-pipeline stage filter that silently misses half your deals is the kind of mistake that becomes a quarterly forecast miss).
Query Streams MCP returns that same cached HubSpot schema enriched with what we call Schema Intelligence (SI) — AI-curated metadata that’s generated by running profiling queries against your actual HubSpot CRM data before the AI client ever asks. When SI is enabled on the HubSpot connector, every schema tool the AI calls (qs_get_connector_schema, qs_get_table_schema, qs_profile_table, qs_get_relationships) returns the bare cached schema plus six layers of curated knowledge. The LLM stops guessing.
To make this concrete, here is what the AI client gets back from a single qs_get_table_schema call against the HubSpot connector’s deals table — the central revenue-pipeline object that drives 80% of CRM reporting questions — first without Schema Intelligence, then with it.
The six layers Schema Intelligence adds
Each layer addresses a specific class of question the LLM would otherwise have to guess at. SI is opt-in per (connector, database) pair and runs as a one-time profiling pass against your data — it does not change your schema, does not write to your database, and refreshes incrementally when your schema changes.
AI-curated descriptions
Plain-English purpose for every database, schema, table, and column — generated once, refreshed when your schema changes. Confidence-scored; user-authored descriptions always win.
opportunity in every HubSpot pipeline.”
Table classifications
Each table tagged FACT (transactional events), DIM (descriptive reference), or LOOKUP (small code maps), plus a business domain — sales, marketing, support, finance, hr, seo, and 14 more.
contacts [DIM, domain:sales]
Semantic types per column
Eighteen types — currency, email, date_iso, status_code, percentage, identifier, url, person_name, and more. The AI generates dialect-correct SQL appropriate to each type, including the hs_object_id string-join treatment no bare-schema LLM gets right.
hs_object_id: identifier (string)
Sample values from real data
Random rows surfaced to the LLM so it recognises patterns no schema can show — formatting conventions, encoded values, naming styles, and the actual shape of your deal names.
“Globex – New Logo – Q3”, “Initech – Expansion”]
Enum detection with distributions
Low-cardinality columns (50 or fewer distinct values, at most 5% of rows unique) mapped to their full value list with row counts. Per-pipeline for dealstage and hs_pipeline_stage — the LLM sees every pipeline’s stages, not just one.
dealstage [Renewal]: closed-won, churned, discovery
Implicit foreign-key discovery
Cross-table data overlap analysis finds joins that aren’t declared as DDL constraints — including custom-object-to-standard-object joins via the hs_object_id association pattern. Stored alongside formal FKs with confidence scores, returned by qs_get_relationships.
companies.hs_object_id (98% overlap, conf 0.97)
Same prompt, different SQL
The proof is in the SQL the AI tool actually writes. Same Cursor session, same Claude model, same prompt — “Show me closed-won deals in the last 90 days, with the contact owner and company, only enabled pipelines.” Without Schema Intelligence the LLM has to guess. With it, the LLM knows dealstage values vary per pipeline, hs_object_id is a string, and the join graph is custom-object-aware.
si_recommendation block telling the AI exactly what it’s missing — including a one-call option to enable SI mid-conversation via qs_request_si_analysis. Your AI client can offer to trigger an SI run on the spot (“would you like me to enable Schema Intelligence on this database first? It runs through your Network Agent in the background and will dramatically improve my answers”). Run time scales with table count: a small database under 100 tables completes in around 10 minutes; a typical mid-size database (a few hundred tables) finishes in 15–25 minutes; a large enterprise database with 1,500+ tables can take 45–60 minutes for a full scan. Subsequent refreshes after schema changes are incremental and much faster than the first run. Schema Intelligence is opt-in. We just don’t think you’ll want to opt out.
Query Streams MCP vs HubSpot Breeze AI and HubSpot’s official AI surfaces
HubSpot ships its own AI: Breeze AI, the in-product co-pilot that writes marketing copy, suggests next-best-actions on deals, and drafts emails for sales reps from inside the HubSpot UI. There’s also an evolving official MCP-style surface that exposes some HubSpot objects to external clients via per-object function calls. These are real products, and they solve a real problem — AI for HubSpot creators working inside HubSpot. Query Streams HubSpot MCP is a different shape: a programmatic SQL surface over the full CRM data model (every standard object plus every custom object) for AI tools working outside HubSpot, with multi-object joins, cross-connector reach, and the same audit + read-only enforcement every Query Streams MCP connector ships with.
JOIN across CRM objects + custom objectsREADONLY_VIOLATION validatorevent_logs per call (org / user / key / scope / latency)They coexist well. Breeze AI is built for HubSpot creators — sales reps, marketers, and support agents working inside the HubSpot UI who want an in-product co-pilot for content generation, next-best-action suggestions, and email drafting. HubSpot’s official MCP coverage is growing and is a good fit for AI agents that need a few specific HubSpot objects via function calls. Query Streams HubSpot MCP is for AI tools working outside HubSpot — Claude, Cursor, ChatGPT, Grok, Windsurf, Zed, and the rest — that need a programmatic SQL surface over your full CRM data model with multi-object joins, cross-connector reach to your Stripe / Postgres / Snowflake / Shopify data, and a single auditable read-only access plane. Most teams that buy Query Streams HubSpot MCP also keep using Breeze AI inside HubSpot. The decision is per-tool and per-AI-agent, not per-org.
MCP not for you? Try Nova AI instead.
If editing JSON config files and installing AI desktop clients sounds like more work than you signed up for, you can skip MCP entirely. Nova AI is built right into the Query Streams web portal — no setup, no configuration, and no separate AI vendor subscription on top of your Query Streams plan. Sign in, click Ask Nova, and ask the same kind of plain-English questions: “what’s pipeline-to-revenue conversion by stage and which stage has the biggest drop-off?” or “show me top 20 accounts by ARR with renewal date in next 90 days, ordered by churn risk score.” Nova already knows about every connector you’ve added — HubSpot, your databases, Stripe, Shopify, Google Ads, all of it — so there’s nothing to wire up. Same Network Agent, same read-only enforcement, same Schema Intelligence powering the SQL. Just no MCP plumbing on your end. Every Query Streams plan includes Nova AI credits; usage draws from your tier just like Excel, Sheets, and the Query Builder.
Meet Nova AIPrerequisites
Before you start, make sure you have:
- A free Query Streams account at my.querystreams.com.
- The Query Streams Network Agent installed on a machine with internet access — see Download the Query Streams Agent. The HubSpot API is reachable from anywhere, so the agent doesn’t need to live on a specific network.
- A HubSpot connector configured against the agent — see the existing API Connector Setup guides for private-app token pairing (recommended) or OAuth user-context apps. The agent holds the HubSpot private-app token, your hub ID, and any OAuth refresh tokens; the AI tool never touches any of them.
- Any MCP-capable AI client. We’ll show Cursor, Claude Desktop, ChatGPT, and Grok in this guide; if you use Windsurf, Zed, Continue, Cline, VS Code Copilot, Codex, or Goose, the config block is essentially the same.
- Five minutes.
Drop it into your AI client
One JSON snippet for Cursor, Claude, ChatGPT, or Grok. Same key everywhere.
Ask a question
“What’s pipeline value by stage this quarter?” — the AI calls the right tools, you get the answer.
Step 1: Generate an MCP key in Query Streams
Sign in to Query Streams and open the MCP page (or sign in first at my.querystreams.com and click MCP in the left navigation). Click Generate key, give the key a recognizable name (something like cursor-laptop or claude-desktop), and pick the scopes you want this key to have:
read— the AI can browse connectors and read schema. Required for everything else.analyze— the AI can profile tables and discover relationships (sample values, distributions, semantic types). Optional but strongly recommended for CRM work, where understanding the shape of your deal data and per-pipeline stage enums matters.execute— the AI can actually run SQL. Without this, the AI is read-only against schema metadata only.
For a typical “let Claude analyse my HubSpot CRM data” workflow, all three scopes are appropriate. For a key you’re handing to a teammate or a less-trusted client, drop execute and let them browse only. You can revoke any key at any time from the same page; the AI client will see MCP_KEY_REVOKED on its next call and stop working immediately. There’s no propagation delay.
Copy the key now — Query Streams shows it once, then stores only a hash. If you lose it, generate a new one. The key looks like qsmcp_ followed by 48 random characters and is what your AI client sends in the X-MCP-Key request header.
Step 2: Add Query Streams MCP to your AI client
The configuration is the same shape across every MCP-capable client — an MCP server entry pointing at https://mcp.querystreams.com with your key in the X-MCP-Key header. Pick your client below.
// Edit ~/.cursor/mcp.json { "mcpServers": { "querystreams": { "url": "https://mcp.querystreams.com", "headers": { "X-MCP-Key": "qsmcp_PASTE_KEY_HERE" } } } }
// Settings → Developer → Edit Config { "mcpServers": { "querystreams": { "url": "https://mcp.querystreams.com", "headers": { "X-MCP-Key": "qsmcp_PASTE_KEY_HERE" } } } }
// Settings → Apps & Connectors → Add MCP Server URL https://mcp.querystreams.com Auth header X-MCP-Key Header value qsmcp_PASTE_KEY_HERE // Requires a paid ChatGPT plan // (Plus / Pro / Team / Enterprise).
// Grok → Settings → Tools { "mcp_servers": [{ "name": "querystreams", "url": "https://mcp.querystreams.com", "auth_header": "X-MCP-Key", "auth_value": "qsmcp_..." }] }
Restart your AI client. On its next start it will discover the eight Query Streams MCP tools listed above and surface them in its tool palette. In Cursor and Claude Desktop you can verify by typing “list connectors” — the AI should call qs_list_connectors and return your HubSpot connector along with anything else you have configured.
Step 3: Ask the AI a HubSpot question
You don’t write SQL — the AI does. You ask a question, the AI picks the right MCP tool, the agent runs the query against your cached HubSpot data, and the answer comes back as text plus tables. Three example prompts to try first:
deals grouped by pipeline + dealstage, summing amount, filtered to active pipelines and the last two months. You’ll see a stacked-by-stage rollup per pipeline plus a written interpretation — which stages are healthy, which have stalled deals piling up, and where conversion is slipping. Schema Intelligence’s per-pipeline enum detection prevents the classic “WHERE dealstage = 'closedwon'” mistake that silently misses deals in your renewal pipeline (where the stage is spelled closed-won with a hyphen).deals to owners via hubspot_owner_id = owners.hs_object_id (string compare — SI’s identifier-string semantic type prevents the bare-LLM mistake of treating the column as numeric), filters dealstage to proposal-equivalent stages across all your pipelines, computes days-in-stage from hs_lastmodifieddate, and pulls the most recent engagement activity per deal owner. The output is a sorted “stuck deals” worklist with the rep email plus a paragraph annotating which deals look like they need a close-or-disqualify decision. The opposite query — “which deal owners have the highest velocity by close rate this quarter?” — is the same SQL inverted and the AI handles it the same way.contacts.hs_analytics_source (or hs_object_source if you’ve configured custom attribution properties) joined to closed-won deals via contacts.hs_object_id and the deal-contact association, summing amount per source channel. The AI tool will usually highlight which channels are over- and under-performing relative to their share of the contact pipeline — organic search vs paid social vs direct vs referral — and propose a follow-up: “want me to layer the same view by lifecycle stage to see where each channel converts best?” Schema Intelligence’s enum detection on hs_object_source ensures the AI doesn’t get confused between FORM / IMPORT / API / INTEGRATION categories that vary across portals.The first time the AI calls a tool, your client may pop up a confirmation prompt asking you to approve the tool call — that’s MCP’s standard consent flow, not anything Query Streams adds. Approve once and the AI proceeds with the rest of the conversation freely. You can revisit the consent at any time in your client’s settings.
Honest billing notice: MCP usage is charged on uncompressed bytes
Query Streams’ Excel add-in, Google Sheets add-on, web Query Builder, and Nova AI all run over our compressed cloud link — we measure and bill compressedBytes against your data realm. The MCP transport (Streamable HTTP per the official MCP spec) does not reliably support compression end-to-end across every client and intermediate proxy, so we measure and bill uncompressedBytes for MCP traffic.
- What this means: a 2 MB HubSpot CRM query (deals + contacts + companies for a quarter, with all your pipelines) costs ~2 MB of your data realm when fetched via MCP, vs. ~250–400 KB via Excel / Sheets / Nova / the Query Builder. HubSpot data compresses well — snake_case enum strings, repeated stage labels, owner ids, and timestamps repeat across rows, so LZ4 over the cloud link typically achieves 6–8x reduction on the other transports. Same data, different transport, different billable size.
- What this isn’t: a markup or a punishment for using MCP. We pass through actual bytes shipped. The other clients are cheaper because compression works reliably on those transports; we don’t punish you for the protocol choice, but we have to be transparent about the cost shape.
- What you can do: for very large recurring exports (e.g. multi-year contact + deal + activity cross-tabs), prefer the Excel / Sheets / Nova path. For interactive AI tool calls (the typical 100–5,000 row HubSpot aggregate that fits in an LLM context), MCP is the right choice and the cost difference is in cents.
Frequently asked questions
Do I need to open ports or run a VPN to use this? +
https://mcp.querystreams.com from the public internet — if outbound HTTPS works on the agent host, MCP works. See how the outbound-only connection works →
Which AI tools can I use with Query Streams MCP? +
Can I revoke an MCP key? +
/mcp page, per-org via plan settings, and platform-level), none of which need a HubSpot private-app token rotation or agent restart. More on MCP key revocation →
How is MCP usage billed against my data realm? +
Does Query Streams MCP work with HubSpot Free / Starter / Professional / Enterprise tiers, OAuth user-context apps vs private-app tokens, and HubSpot custom objects? +
goals, feedback_submissions, full custom-object support) on Professional and Enterprise. Auth: private-app tokens (recommended for server-to-server use) or OAuth user-context apps (for delegated access). Private apps are easier to operate — generate a token in Settings → Integrations → Private Apps, scope it to read-only on the specific objects you want the AI to see (e.g. CRM contacts read, CRM deals read, CRM companies read), and store it in the agent’s encrypted credential store. Token rotation is a regenerate-and-swap; no password ceremony required. Custom objects are auto-discovered by Schema Intelligence — the SI scan reads HubSpot’s schemas endpoint and surfaces every custom object you’ve configured as a clean SQL table with friendly column names (the API returns property ids like 2_12345__property_name; SI flattens them to property_name with the integer prefix preserved as table-name disambiguation). Custom-object joins to standard objects (e.g. linking a custom invoices object to companies) use the standard hs_object_id association pattern and work in SQL exactly like any other join.
How does this differ from running an open-source HubSpot MCP server myself? +
dealstage enum awareness baked in. You also pick up Schema Intelligence, agent-layer read-only enforcement, per-key rate limits, audit trail in event_logs, and the same data-realm billing pipeline you already use — none of which a direct MCP gives you.
What happens if the AI tries to write or delete data? +
SELECT / WITH / EXPLAIN and returns READONLY_VIOLATION on anything else. There’s a HubSpot-specific second layer on top — write/mutate operations (creating contacts, updating deal stages, deleting companies, sending emails) are never exposed to the MCP surface in the first place, so the agent only ever issues read-shaped v3 API calls and the LLM has nothing it could call to mutate your CRM. How agent-layer read-only enforcement works →
Can I see what the AI actually asked? +
event_logs (org, user, key, scope, latency, result code), logging the tool name and metadata rather than the SQL text or rows. Because HubSpot’s own activity log captures UI activity but doesn’t expose third-party AI access in a queryable shape, the agent’s event_logs is the cleanest record of “what did the AI ask, against which HubSpot portal, when” — in your own database, not split between HubSpot’s audit trail and your AI client’s history. More on the MCP audit trail →
Do I have to run Schema Intelligence to use Query Streams MCP? +
(connector, database) pair and MCP works on bare schema without it, but enabling it adds six layers of curated metadata (descriptions, FACT/DIM/LOOKUP classifications, per-column semantic types, real sample values, enum distributions, and discovered foreign keys) that make the AI write correct SQL first try. For HubSpot the decisive layer is per-pipeline dealstage enumeration — the LLM sees every pipeline’s stages (including closedwon vs the hyphenated closed-won) plus the hs_object_id string-join treatment a bare schema never reveals. What Schema Intelligence adds and how long a scan takes →
What if I add another connector later, like Stripe or PostgreSQL? +
qs_list_connectors picks it up automatically). One config block buys your whole account, present and future. Why one key covers every connector →
Do I have to set up MCP just to chat with my data? +
Why use Query Streams MCP for HubSpot data if HubSpot ships Breeze AI and an official MCP-ish surface? +
deals / companies / contacts / owners. Breeze AI inside HubSpot can answer single-record questions; Query Streams MCP can answer multi-object analytical queries. (2) Multi-connector single key. Combine HubSpot data with your Stripe revenue + your Postgres product database in the same Claude conversation. Ask “show me HubSpot deals with no Stripe charges in the last 30 days, segmented by sales owner” — a cross-system join Breeze AI can’t reach. (3) Programmatic + auditable. Every Query Streams MCP call lands in event_logs with org / user / key / scope / latency. Compliance teams can answer “who queried HubSpot CRM data last week and what did they ask?” with one query. Breeze AI activity stays in HubSpot’s own audit log, separate from your other AI tool usage. They coexist well. Use Breeze AI for in-HubSpot creator tasks; use Query Streams MCP when AI tools outside HubSpot need CRM data with cross-system joins.
Get started
Connect your AI tool to your HubSpot CRM data in five minutes.
One MCP key reaches HubSpot, every database, and every other API connector in your Query Streams account — with full audit trail, per-key rate limits, multi-object SQL joins, custom-object support, and zero firewall changes. Claude, Cursor, ChatGPT, and Grok all work out of the box.
Related guides: Download the Query Streams Agent | API Connector Setup | All MCP Server guides | Nova AI text-to-SQL
Category: MCP Server
Tags: mcp, claude, cursor, hubspot, api-connector, crm, sales-analytics, marketing-analytics, breeze-ai, read-only-mcp
Meta Description: Query HubSpot CRM with Claude or Cursor via MCP. Multi-object SQL joins, custom objects, no firewall holes. Free.
English 
Spanish 
German 
French 
Portuguese 
Japanese 
Korean 
Chinese 
Italian 
Dutch 
Indonesian 
Polish