connect-hubspot-mcp

name	connect-hubspot-mcp
description	Connect Claude Code to HubSpot's official remote MCP server for natural-language CRM reads and writes. Covers OAuth setup, scope selection, verification, and when to use MCP versus this repo's API scripts.
license	MIT
metadata	{"author":"tomgranot","version":"1.1","category":"audit-planning"}

Connect Claude Code to HubSpot via MCP

Set up HubSpot's official remote MCP server so Claude can read and write CRM records conversationally — look up a contact, inspect a company's deals, spot-check the results of a cleanup — without writing a script for every question.

What the MCP Server Is (and Isn't)

HubSpot's remote MCP server (generally available since April 2026) is an OAuth-secured gateway at mcp.hubspot.com that exposes CRM operations as tools to MCP clients like Claude Code:

• Read/write CRM objects: contacts, companies, deals, tickets, line items, products, engagements
• Read content: campaigns, landing pages, website pages, blog posts, and content analytics
• Create content: landing pages (added June 2026)

It is the right tool for interactive, judgment-heavy work: spot-checks, triage, one-off lookups, small targeted edits. It is the wrong tool for bulk operations: batch-archiving thousands of contacts, paginated sweeps, or anything that needs a CSV audit trail and an abort threshold. That is what this repo's scripts are for. The two share the same portal — use both.

Task shape	Use
"Show me 5 contacts the cleanup touched"	MCP
"Why is this company in Tier 2?"	MCP
"Review this week's bounce-flagged contacts"	MCP
"Delete 4,000 no-email contacts with an audit trail"	Scripts (/delete-no-email-contacts)
"Create 10 segmentation lists"	Scripts (/build-smart-lists)
"Export every workflow to JSON"	Scripts (/workflows-as-code)

Prerequisites

• A HubSpot account and a user with permission to create user-level apps (or approval via your portal's MCP Auth Apps governance, if enabled)
• Claude Code (or another MCP client)
• This is separate from the private app token the scripts use — MCP connects via OAuth as you, with your HubSpot permissions

Execution Pattern

Stage 1: Plan

1. Decide the scopes to grant. Start read-only (CRM object read scopes); add write scopes only if you want Claude making edits through MCP.
2. Check with your admin whether the portal restricts app installs (App Install Governance) — MCP connections may need approval.

Stage 2: Execute — Connect

Option A: HubSpot Connector for Claude (no terminal). In Claude's connector settings, add the HubSpot connector and complete the OAuth flow in the browser. HubSpot's guide: knowledge.hubspot.com > "Set up and use the HubSpot connector for Claude".

Option B: MCP client configuration. Add the remote server to Claude Code:

claude mcp add --transport http hubspot https://mcp.hubspot.com

Then authenticate when prompted — the OAuth flow creates a user-level app with the scopes you approve.

Option C: HubSpot CLI. With HubSpot CLI v8.2.0+, hs mcp setup walks through connecting an MCP client, and also offers HubSpot's local developer MCP server (aimed at app development rather than CRM administration).

Stage 3: After — Verify

Ask Claude to perform a harmless read and confirm it round-trips:

"Using the HubSpot MCP tools, fetch one contact and tell me its email and lifecycle stage."

If the call fails: check that the OAuth flow completed, the scopes include contact read, and your portal hasn't blocked the connection via app governance.

Rollback

• Disconnect the MCP server from your client settings (claude mcp remove hubspot in Claude Code).
• Revoke the connection in HubSpot: Settings > Integrations > Connected Apps — removing the user-level app invalidates its tokens.

Technical Gotchas

1. MCP access is user-scoped. Claude can do exactly what your HubSpot user can do — no more, no less. Bulk-risky operations are naturally bounded by the scopes you grant; grant write scopes deliberately.
2. Two credentials, two purposes. HUBSPOT_ACCESS_TOKEN (private app) powers the scripts; the MCP OAuth connection powers conversational access. Rotating one does not affect the other.
3. Rate limits still apply. MCP calls consume the same API capacity as any integration. Don't use MCP for high-volume sweeps — that's script territory.
4. Headless environments. MCP servers that require interactive OAuth may be unavailable in scheduled/CI runs. Scripts with a private app token work everywhere; treat MCP as the interactive layer.