MCP Server for HubSpot

HubSpot's API stops at 10k records. We don't.

HubSpot's official MCP server gives AI assistants read-only access to your CRM - capped at 10k records. g-gremlin-hubspot-mcp gives them the full toolkit: pull every record in your portal, detect and merge duplicates, track property drift, diff CRM snapshots, and bulk upsert - all from Claude Desktop, Cursor, Windsurf, or OpenClaw via mcporter.

With dry-run safety on every mutation.

Public beta is live. Read tools like query, pull, and dedupe planning work without an account. Start a 30-day trial to unlock licensed write and admin tools.

Start 30-Day Free Trial See the Comparison

Claude Desktop

You:

Find duplicate contacts by email in my HubSpot

Claude:

Running hubspot.dedupe.plan with match_field="email"...

Merge Plan Preview (dry-run)

Found 847 duplicate groups across 2,134 contacts

Largest group: 12 records ([email protected])

plan_hash: sha256:a3f8c2...

No records merged. Pass apply=true with plan_hash to execute.

OpenClaw (Community-Supported)

OpenClaw users can run this MCP server through mcporter while we stay focused on IDE-first onboarding in public beta.

{ "mcpServers": { "g-gremlin-hubspot": { "command": "g-gremlin-hubspot-mcp", "env": { "G_GREMLIN_HUBSPOT_ACCESS_TOKEN": "YOUR_TOKEN" } } } }

Start with the short answers

If the user query is about MCP choice, tradeshow imports, or lead-status orchestration, start with these question pages and then drill into the full MCP surface.

Best HubSpot MCP server

Question-first comparison for choosing the right HubSpot MCP surface for AI agents.

Open guide

ICP and persona guide

How to build an ICP and buyer-persona model from staged HubSpot exports instead of relying on anecdote or one dashboard.

Open guide

HubSpot tradeshow guide

How to clean, dedupe, and upsert event files into HubSpot without turning the portal into a duplicate mess.

Open guide

HubSpot lead-status guide

How to separate lifecyclestage from hs_lead_status and keep the automation reviewable.

Open guide

What RevOps Teams Actually Need

Every feature exists because someone hit a wall with the existing options.

HubSpot's API caps search at 10k records

Auto-windows by date range to pull your entire portal

No way to find duplicates from an AI assistant

Scans by any field (email, domain, external ID), generates a merge plan

Mutations are scary when an AI is driving

Every write is dry-run by default. Apply requires a cryptographic plan hash from the preview step

"What changed in our CRM since last quarter?"

Snapshot your CRM state, diff two snapshots, see exactly what moved

Property definitions drift from the spec

Compares your YAML/JSON spec against the live portal, reports additions/removals/changes

Bulk updates require CSV upload in the UI

Upsert from CSV with dry-run preview and batch error reporting

Engagement data is capped and fragmented

Pulls emails, calls, meetings, notes, tasks - auto-falls back to async export when capped

Side-by-Side Comparison

We looked at what HubSpot's MCP server actually does vs. what RevOps teams need. Then we built the rest.

Capability	HubSpot Official	Community MCP	g-gremlin-hubspot-mcp
Records past 10k	No (hard cap)	No (caching workaround)	Yes - auto-windowing
Write operations	No	Create-only	Upsert with dry-run
Duplicate detection	No	No	Merge plans
Schema & property mgmt	No	No	Full introspection + drift
Engagement export	No	No	Async fallback
CRM state diffing	No	No	Snapshot + compare
Safety model	None	None	Dry-run + plan hash

How We Break the 10k Ceiling

HubSpot's Search API has a hard cap of 10,000 total results - no cursor beyond that. Here's how we get every record anyway.

Initial query hits the 10k ceiling

Inspects createdate timestamps in returned records

Binary-splits the time range, re-queries each window

Repeats recursively (max depth 8, min window 7 days)

Deduplicates across windows by record key

Auto-windowing in action

Query: all contacts

Hit 10k ceiling

Split: 2020-01-01 → 2023-06-15

Split: 2023-06-15 → 2026-01-01

Window A: 8,234 records OK

Window B: hit 10k ceiling

Split: 2023-06-15 → 2024-09-08

Split: 2024-09-08 → 2026-01-01

Window B1: 6,891 records OK

Window B2: 9,106 records OK

Total: 24,231 records (3 windows, deduplicated)

14 MCP Tools

Consistent JSON response envelope. Impact classification on every response. Per-tool timeouts up to 15 minutes for large pulls.

Tier 1: Read & DiscoverREAD

hubspot.auth.whoami

Check auth, show portal identity

hubspot.auth.doctor

Health diagnostics (connectivity, scopes, API access)

hubspot.schema.list

List all CRM object types (standard + custom)

hubspot.schema.get

Full schema for an object type (properties, associations)

hubspot.props.list

Property introspection (names, types, labels)

hubspot.objects.query

CRM search with filters (Search API, capped at 10k)

hubspot.objects.pull

Full extraction past the 10k ceiling (auto-windowing)

hubspot.engagements.pull

Engagement pull with async export fallback

Tier 2: Analyze & PlanANALYZE

hubspot.dedupe.plan

Scan for duplicates, generate merge plan with plan_hash

hubspot.props.drift

Detect property drift between spec and live portal

hubspot.snapshot.create

Capture CRM state (schema, props, counts)

hubspot.snapshot.diff

Compare two snapshots, show what changed

Tier 3: MutateWRITE / MERGE

hubspot.objects.upsert

Bulk upsert from CSV (dry-run default, two-phase apply)

hubspot.dedupe.apply

Execute a merge plan (requires plan_hash verification)

Two-Phase Safety on Every Mutation

Nothing writes to your CRM until you've reviewed the plan. Every mutation requires a cryptographic hash.

Dry-Run (default)

Tool runs without making changes. Returns a full preview of what would happen, plus a SHA-256 plan_hash.

"dry_run": true,

"plan_hash": "sha256:a3f8c2e9...",

"preview": { "groups": 847, "records": 2134 }

Apply (explicit)

Caller passes apply=true AND the plan_hash. If the hash doesn't match - wrong plan, stale data, different file - rejected with a clear error.

"apply": true,

"plan_hash": "sha256:a3f8c2e9...",

"ok": true, "merged": 847

Built for Your Role

⚙️

RevOps / CRM Admins

Stop clicking through HubSpot settings. Ask Claude to audit your properties, find duplicates, and preview bulk changes - with guardrails that won't let anything run until you say so.

🛠️

Developers / Data Engineers

14 MCP tools. Consistent JSON response envelope. Two-phase mutation safety with SHA-256 plan hashing. Per-tool timeouts up to 15 minutes for large pulls. pip install and go.

💡

AI-Curious Ops Teams

You've heard AI can help with CRM work. But HubSpot's MCP only lets it read 10k records. This is the one that actually does the job.

PUBLIC BETA

Start Free Trial

Public beta is live. Start a 30-day free trial for full access.

Start 30-Day Free Trial

Setup takes about 2 minutes:

Install

pipx install g-gremlin && pipx install g-gremlin-hubspot-mcp

Connect to HubSpot

g-gremlin hubspot connect --access-token YOUR_TOKEN

Add to your MCP client

Claude Desktop/Cursor/Windsurf: one JSON block. OpenClaw: use mcporter bridge.

FAQ

Common Questions

How is this different from HubSpot's official MCP server?

HubSpot's official server gives AI assistants read-only search capped at 10,000 records. We add auto-windowing past 10k, write operations with dry-run safety, duplicate detection with merge plans, schema introspection, property drift detection, engagement export with async fallback, and CRM state diffing.

Is it safe to let an AI write to my HubSpot?

Every mutation is dry-run by default. The dry-run produces a preview and a SHA-256 plan hash. To apply, the AI must pass both apply=true AND the exact plan hash. If anything changed between preview and apply, the hash won't match and the operation is rejected.

How does it get past the 10k record limit?

We use recursive date-range windowing. When a query hits the 10k ceiling, we inspect createdate timestamps, binary-split the time range, and re-query each window. This repeats recursively (max depth 8, min window 7 days) until every record is captured, with deduplication across windows.

Which MCP clients are supported?

Claude Desktop, Cursor, Windsurf, and any MCP-compatible client. OpenClaw is supported via the mcporter bridge (community-supported path).

Can I use this with OpenClaw?

Yes. OpenClaw users can run this server through mcporter. Add g-gremlin-hubspot-mcp in mcporter using stdio transport, then call MCP tools from OpenClaw through the mcporter skill/runtime. This path is community-supported in public beta.

How do I install it?

pipx install g-gremlin, pipx install g-gremlin-hubspot-mcp, connect to HubSpot with a Private App token, and add the server to your MCP client config. Full setup takes about 2 minutes.

Your AI assistant just got HubSpot admin access.

Public beta is live. Start a 30-day free trial for full access.

Start 30-Day Free Trial See Full HubSpot CLI