MCP
HubSpot MCP server: CRM counts, not contact records, from Claude or Codex
TL;DR
HubSpot's official remote MCP server has been generally available since 13 April 2026 and reads and writes CRM records with your own HubSpot permissions. This guide covers a HubSpot MCP server with a narrower contract: deals, won revenue and new contacts as counts beside ad spend, and no contact's email, phone or name ever returned over MCP.
What HubSpot's official server gives you
HubSpot's remote MCP server at mcp.hubspot.com became generally available on 13 April 2026. It authenticates with OAuth 2.1 and PKCE, respects the connecting user's own HubSpot permissions, and reads CRM records, marketing campaigns, landing pages and activity history.
- It writes too — creating and updating contacts, companies, deals, tickets, line items, products and activities — while quotes, invoices, orders and marketing content can only be read.
- A separate developer MCP server runs locally for building HubSpot apps and CMS content — a different tool for a different job.
- It works as you. Whatever your HubSpot user can see, contact records included, the assistant can see.
For working inside the CRM from chat, HubSpot's server is the direct route. The rest of this page is about joining the CRM to ad spend without handing contact records to a model.
What a full MCP server adds
| HubSpot's official server | Agent Planners MCP | |
|---|---|---|
| HubSpot tools | CRM, marketing and activities | 17 reads, 31 writes |
| Contact emails, phones, names | Returned when your user can see them | Never returned over MCP |
| Deal and contact attribution by source | Records to aggregate yourself | Counted server-side, with win rates |
| Contact writes, list membership, deletes | As your user | Held for a person on every key mode |
| Ad spend in the same session | No | Google Ads, Meta, Microsoft and the rest on the same key |
Counted from the tool registry, which the MCP catalogue matches one for one:
tools/list offers 48 HubSpot tools of the 1012 on the endpoint (a key that lists its tools on demand reaches the same ones with search_tools and call_tool). The reads work on the default connection; every write scope is optional and reaches the grant only where it has been enabled and the portal re-authorized.How to configure it
- 1Create a key in API & MCP.
tools:readfor reporting; addtools:writefor CRM changes, which follow the key's write mode. Tools mode needs a paid plan and fails closed. - 2Connect HubSpot under Integrations as a Super Admin, or a user with the Marketplace access permission, and pick the portal. The default grant holds read scopes: contacts, deals, owners and lists, plus companies, marketing campaigns, campaign revenue and traffic reports where your plan includes them.
- 3Add the server to Claude Code, Claude Desktop or Codex with the snippet below.
- 4Run
describe_permissions, thenlist_accountsfor the portal id.
bash
claude mcp add --transport http agentplanners https://www.agentplanners.com/api/mcp \
--header "Authorization: Bearer ap_live_…"Codex uses the same endpoint from
~/.codex/config.toml, with the key in an environment variable rather than the file: [mcp_servers.agentplanners] / url = "…/api/mcp" / bearer_token_env_var = "AGENTPLANNERS_API_KEY".Personal data never returns over MCP
A contact's email, phone number or name is withheld over MCP whatever the key's scopes: hubspot__search_crm refuses personal properties on the MCP lane, and hubspot__get refuses contact records and list memberships by path. Ask for counts instead — new contacts by source and lifecycle stage are exact, and nothing about a person has to leave HubSpot to produce them.
Inside the app, a person's own request can still name personal fields on specific people, capped at 20 rows — never on a schedule, an API task, an autonomous run or over MCP.
What waits for a person, whatever the key allows
These are held in the approval queue on every key mode, emailed to an accountable admin or editor, and decided one at a time — never inside a bulk approval.
- Every delete, archive or removal, and every contact write — contacts are personal data.
- List membership changes. A list is a workflow enrollment trigger, and workflows email people.
- Tasks, because HubSpot notifies the assignee, and stage, owner or lead-status changes on a deal or company — the usual enrollment triggers.
- Publishing a landing page, a public file, or a live custom event — test mode is the default.
Refused outright on every lane: the marketing-contact status (HubSpot bills per marketing contact), the email opt-out and consent properties, dynamic lists, and every payment, refund, invoice or subscription write — none of those is a tool.
No raw_request tool — the typed gateway instead
There is no hubspot__raw_request. hubspot__get reaches the reads through a path allowlist and the personal-data fence above; a passthrough for external keys would bypass both.
Why HubSpot and your ad platforms disagree
- Ad platforms count their own conversions inside their own attribution windows; HubSpot records where each lead first came from.
- A deal's source is copied from its earliest contact, so it says which channel brought the lead in — not which ad closed it.
- Deal amounts are in the portal's company currency; deals in other currencies are listed apart, never added in.
Two setup details: while the app is not yet listed on the HubSpot Marketplace, HubSpot asks the installer to type "I accept the risk"; and campaign, form and email reporting needs Marketing Hub Professional or Enterprise.
Use cases
- Cost per won deal by channel — spend from each ad platform against HubSpot's closed-won revenue by original source.
- Lead quality by campaign — new contacts by source and lifecycle stage, counted, beside what each ad platform says it converted.
- Pipeline anomalies — daily new contacts, deals created and deals won, with alert rules on the same series.
- Tracking gaps — landing pages and the portal's tracking code checked from the ad side.
Frequently asked questions
- Is there an official HubSpot MCP server?
- Yes. HubSpot's remote MCP server at mcp.hubspot.com has been generally available since 13 April 2026, with OAuth 2.1 and PKCE, reads across the CRM and marketing content, and creates and updates on core objects. A separate developer MCP server runs locally for app and CMS development.
- Does this HubSpot MCP server return contact details?
- No. Emails, phone numbers and names are never returned over MCP, whatever the key's scopes; questions are answered in counts and totals.
- Can an agent change my HubSpot CRM over MCP?
- Only where the optional write scopes have been enabled and the portal re-authorized. Ordinary writes follow the key's write mode — queued for approval, or run inside the guardrails — and a person approves every contact edit, list membership change, task, stage or owner change, delete and page publish, whatever the key allows.
- Why does HubSpot credit a different channel than Google Ads?
- HubSpot records the source that first brought a contact in and copies it to their deals; Google Ads counts its own conversions inside its own window. Both are shown side by side rather than added together.