Claude Code MCP HubSpot Setup
The official server, OAuth, scoped permissions, and the workflows GTM Engineers actually wire up.
Why Wire Claude Code to HubSpot
HubSpot sits at the center of the CRM market for most B2B SaaS GTM teams. Claude Code becomes a real GTM tool the moment it can read and write to that CRM directly. Account research that updates the deal record. Pre-call briefs that pull the latest activity. Enrichment workflows that score and route. Reply triage that logs the outcome. None of those work if the agent has to wait for a human to copy data in and out.
HubSpot publishes an official MCP server at https://mcp.hubspot.com/anthropic. It's a remote HTTP server. Authentication runs through OAuth inside the Claude Code session, which is the safer pattern. There's no API key sitting in a config file waiting to leak. The OAuth scopes you grant during the connect flow control what the agent can do.
Honest framing before the steps. The MCP server is the bridge. It doesn't write the prompt for you, it doesn't pick the right scopes, and it doesn't catch a bug in your workflow that updates the wrong field on 500 records. Wire the integration with the same care you'd give any production CRM connection.
Step 1: Add the MCP Server
The command is one line:
claude mcp add --transport http hubspot https://mcp.hubspot.com/anthropic
This registers the HubSpot server in your local Claude Code config. The first time you use it in a session, run /mcp and select hubspot. Claude Code opens a browser window to HubSpot's OAuth screen. You log in, approve the scopes, and the token gets stored.
For team projects, write the server into a project-scoped .mcp.json so your teammates pick up the same config. Their tokens are still personal, scoped to their HubSpot user, but the connection wiring travels with the repo:
{"mcpServers": {"hubspot": {"transport": "http", "url": "https://mcp.hubspot.com/anthropic"}}}
One trap. If your HubSpot account uses SSO with a corporate IdP and per-app conditional access, the OAuth flow may bounce on first run. Have your admin pre-approve the Claude Code OAuth app (the connection name as it appears in HubSpot's "Connected apps" admin) before the team tries to wire it.
Step 2: Pick the Right Scopes
HubSpot's OAuth scopes control what the agent can touch at the API level. Granting too much is a real risk. An agent with full account write access plus a vague prompt can update fields you didn't intend.
For a read-only research workflow:
crm.objects.companies.readcrm.objects.contacts.readcrm.objects.deals.read
For an enrichment workflow that writes scores and properties:
crm.objects.companies.writecrm.objects.contacts.writecrm.schemas.contacts.read (to discover available properties)
For meeting prep and logging automation:
crm.objects.meetings.readcrm.objects.meetings.writecrm.objects.notes.write
For deal hygiene workflows:
crm.objects.deals.readcrm.objects.deals.write
The principle is the same as any other API integration. Smallest scope that does the job. If you're not sure, start read-only. Add write scopes as the workflow needs them, not all at once because it's faster.
Step 3: Wire Up a Workflow
Three workflows cover most of what GTM teams ship first.
Account research that updates the CRM. The agent reads the list of recently created or updated company records, runs research (firmographic, news, hiring signals), writes a one-paragraph summary to a custom company property called "ai_research_summary", and updates "last_ai_research_date" with today's date. Frequency: hourly cron or triggered on new company create. See the Claude Code sales agent guide for the broader pattern.
Pre-call briefs. The agent reads the calendar for tomorrow's booked calls, pulls the related HubSpot company and deal records, summarizes recent activity (emails, meetings, notes), surfaces the open opportunity stage and next steps, and writes a one-page brief into a Notion page or a Slack DM. Frequency: nightly cron at 8 PM. The pulse report template shows the structure.
Lead scoring on inbound. The agent reads new contacts created in the last hour, calls the Clay enrichment, scores against the ICP rules in CLAUDE.md, writes the score to a custom property, and routes high-score contacts to a Slack channel. Frequency: every 15 minutes or triggered by webhook. The enrichment workflow guide covers this pattern end to end.
Step 4: Guardrails Before You Trust It
An agent with HubSpot write access is one bug away from updating the wrong field on every contact in the CRM. Wire these before the first batch run.
Property allow list. A PreToolUse hook that rejects any write to a property not on your explicit list. Even if the prompt is sloppy, the hook holds. The list is a short JSON file. Keeping it in the repo means changes get reviewed.
Batch caps. Cap the run at 100 to 200 records. HubSpot's rate limits are forgiving but not unlimited, and a bug that updates 50,000 records in one run is a real day-killer.
Idempotency on writes. Every update includes a check on the existing value. If the value the agent wants to write equals what's already there, skip. This avoids cluttering the activity timeline and avoids spurious "last modified" timestamps that confuse other workflows.
Provenance fields. When the agent writes a property, also write a sibling property with the source and timestamp. "ai_research_summary" gets a sibling "ai_research_summary_updated_by" set to "claude-code" and "ai_research_summary_updated_at" set to the run timestamp. Three months from now, someone debugging a weird value can tell whether a human or the agent wrote it.
Step 5: Test on 20 Records, Then Schedule
Same discipline as every other agent build. Run the workflow on 20 records. Open each one in HubSpot by hand. Verify the property values match what the agent should have written. Verify the timestamps. Verify no fields were touched that shouldn't have been.
When you find a miss, fix the prompt, the hook, or the scope. Don't hand-edit the bad record. A patched record hides the bug and the next run reproduces it. Rerun the 20, recheck the 20, repeat until clean.
Once a 20-record run is consistently right, schedule the headless command on a cron job. Pipe the log to a file. Pipe failures to Slack. Watch the dashboard, not the run.
Where Teams Get Stuck
Three common failures. Rate limit cascades. The agent processes a batch, hits the per-10-second limit, retries, hits it again, retries faster. The fix is to use HubSpot's batch endpoints (the MCP server exposes them) and add exponential backoff in the prompt with a hard retry ceiling.
OAuth token expiry mid-run. A long batch hits the token refresh window, the run fails, the cron logs an error. The fix is the /mcp auto-refresh, which works inside an interactive session but needs the right config flag for headless runs. Check the HubSpot OAuth documentation for the refresh token lifetime in your account.
Custom property name drift. A teammate renames a custom property in HubSpot, the agent's prompt still references the old internal name, writes fail silently or to the wrong field. Read the property schema at the top of every run, log a clear error if the expected property doesn't exist.
For the Salesforce equivalent, see Claude Code MCP Salesforce. For the broader MCP setup patterns, see the Claude Code sales agent guide. For the underlying CRM hygiene logic, the CRM hygiene playbook covers what an agent should and shouldn't touch.
Authoritative References
For the exact MCP commands and transports, see Anthropic's Claude Code MCP documentation. For HubSpot OAuth scopes and the CRM API rate limits, see the HubSpot OAuth documentation.
Frequently Asked Questions
What is the official HubSpot MCP server URL for Claude Code?
HubSpot publishes a remote MCP endpoint at https://mcp.hubspot.com/anthropic. You add it with claude mcp add --transport http hubspot https://mcp.hubspot.com/anthropic. Authentication runs through OAuth inside the Claude Code session using the /mcp command. There's no API key to paste into a config file, which is the safer pattern. The endpoint and the OAuth flow are documented in HubSpot's developer docs.
What HubSpot scopes does the MCP server need for GTM workflows?
For a read-only workflow (account research, pre-call briefs), you need crm.objects.companies.read, crm.objects.contacts.read, and crm.objects.deals.read. For workflows that write to HubSpot (enrichment, score updates, note logging), add the .write versions of each. For meeting log automation, add crm.objects.meetings.write. The principle: smallest scope that does the job. Don't grant write access to a workflow that only reads.
Can Claude Code write contact properties through the HubSpot MCP server?
Yes, when the OAuth scope includes write access. The MCP server exposes the standard CRM object operations: create, update, and search across contacts, companies, and deals. The agent calls these through the MCP interface the same way it calls any other tool. The most common GTM use case is updating a custom property (ICP score, last enrichment date, AI-generated summary) based on agent output.
How do I limit which HubSpot fields the agent can read or write?
Two layers. The HubSpot OAuth scope is the first. It controls which object types and operations the agent can touch at the API level. The second layer is in your prompt or your hook: explicitly list the properties the agent is allowed to read and write. A PreToolUse hook can reject any write to a property not on your allow list. This matters because a permissive OAuth scope plus a vague prompt can let the agent update fields you didn't expect.
What's the most common failure mode when wiring Claude Code to HubSpot?
Hitting the API rate limit on a batch run. HubSpot's standard API rate limit is 100 requests per 10 seconds for most operations. An agent processing 500 contacts with multiple property reads per contact will trip it within the first batch. The fix is two-fold: batch reads using HubSpot's batch endpoints (which the MCP server should expose), and add exponential backoff with a hard ceiling in your prompt. The second-most-common failure is OAuth tokens expiring mid-run, which the /mcp command refreshes if you let it.
Source: State of GTM Engineering Report 2026 (n=228). Salary data combines survey responses from 228 GTM Engineers across 32 countries with analysis of 3,342 job postings.