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, or Windsurf.
With dry-run safety on every mutation.
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.
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 ✓
Window B: hit 10k ceiling
Split: 2023-06-15 → 2024-09-08
Split: 2024-09-08 → 2026-01-01
Window B1: 6,891 records ✓
Window B2: 9,106 records ✓
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 & Discover READ
hubspot.auth.whoamiCheck auth, show portal identity
hubspot.auth.doctorHealth diagnostics (connectivity, scopes, API access)
hubspot.schema.listList all CRM object types (standard + custom)
hubspot.schema.getFull schema for an object type (properties, associations)
hubspot.props.listProperty introspection (names, types, labels)
hubspot.objects.queryCRM search with filters (Search API, capped at 10k)
hubspot.objects.pullFull extraction past the 10k ceiling (auto-windowing)
hubspot.engagements.pullEngagement pull with async export fallback
👁 Tier 2: Analyze & Plan ANALYZE
hubspot.dedupe.planScan for duplicates, generate merge plan with plan_hash
hubspot.props.driftDetect property drift between spec and live portal
hubspot.snapshot.createCapture CRM state (schema, props, counts)
hubspot.snapshot.diffCompare two snapshots, show what changed
⚠ Tier 3: Mutate WRITE / MERGE
hubspot.objects.upsertBulk upsert from CSV (dry-run default, two-phase apply)
hubspot.dedupe.applyExecute 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 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. Mismatched hash = rejected.
"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. 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.
Get Early Access
The HubSpot MCP server is in private beta. Request access and we'll get you set up within 24 hours.
Once accepted, setup takes about 2 minutes:
Install
Connect to HubSpot
Add to your MCP client
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?
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. 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. Configuration is a single JSON block in your client's MCP settings.
How do I install it?
pip install g-gremlin 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.
Currently in private beta. Request access and we'll get you running within 24 hours.