g-gremlin-hubspot-mcp

Status: Public Beta — 14 tools shipping, core workflows stable, feedback welcome. See Known Gaps below.

The HubSpot MCP server for teams that hit the API ceiling.

HubSpot's official MCP gives you read-only search capped at 10k records. This one gives you dedup merge plans, auto-windowing past the ceiling, property drift detection, and bulk upserts — all from Claude Desktop, Cursor, or Windsurf.

Powered by g-gremlin, the CLI for Google Workspace and CRM automation.

Quickstart

# 1. Install
pipx install g-gremlin
pipx install g-gremlin-hubspot-mcp

# 2. Connect to HubSpot (one-time)
g-gremlin hubspot connect --access-token YOUR_PRIVATE_APP_TOKEN

# 3. Add to your MCP client

Claude Desktop

Add to your claude_desktop_config.json:

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

Cursor / Windsurf

Add to your MCP settings:

{
  "mcpServers": {
    "g-gremlin-hubspot": {
      "command": "g-gremlin-hubspot-mcp"
    }
  }
}

OpenClaw (community-supported via mcporter)

OpenClaw can call MCP servers through mcporter.

1. Install mcporter:

npm install -g mcporter

2. Add this MCP server in your mcporter config:

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

3. Use OpenClaw with the mcporter skill/runtime to list and call tools from g-gremlin-hubspot.

How it compares

Capability	HubSpot Official MCP	peakmojo/mcp-hubspot	g-gremlin-hubspot-mcp
CRM search	10k cap	cached/vector	Auto-window past 10k
Write operations	No	Create only	Upsert + dry-run
Duplicate detection	No	No	Merge plans
Schema introspection	No	No	Full schema/props
Engagement export	No	No	Async fallback
Snapshot diffing	No	No	Yes
Safety layer	N/A	None	Dry-run + plan hash
Impact classification	No	No	Per-tool labels

How we break the 10k ceiling

HubSpot's Search API has a hard cap of 10,000 total results — no cursor beyond that.

g-gremlin breaks this with recursive date-range windowing:

1. Initial query hits the 10k ceiling
2. Inspects createdate timestamps in returned records
3. Splits the time range into binary halves, re-queries each window
4. Repeats recursively (max depth 8, min window 7 days)
5. Deduplicates across windows by record key

Required: createdate (default) or any sortable date property. For objects without timestamps, engagements use an async export fallback with no ceiling.

Available tools

7 tools work with no account (FREE). 7 require a g-gremlin HubSpot Admin license or active trial. A 30-day trial is available at first install.

Tier 1: Read & Discover

Tool	Impact	License	What it does
hubspot.auth.whoami	[READ]	FREE	Check auth, show portal identity
hubspot.auth.doctor	[READ]	Licensed	Health diagnostics (connectivity, scopes, API access)
hubspot.schema.list	[READ]	FREE	List all CRM object types (standard + custom)
hubspot.schema.get	[READ]	FREE	Full schema for an object type (properties, associations)
hubspot.props.list	[READ]	Licensed	Property introspection (names, types, labels)
hubspot.objects.query	[READ]	FREE	CRM search with filters (Search API, capped at 10k)
hubspot.objects.pull	[READ]	FREE	Full extraction past the 10k ceiling (auto-windowing)
hubspot.engagements.pull	[READ]	FREE	Engagement pull with async export fallback

Tier 2: Analyze & Plan

Tool	Impact	License	What it does
hubspot.dedupe.plan	[ANALYZE]	FREE	Scan for duplicates, generate merge plan with plan_hash
hubspot.props.drift	[ANALYZE]	Licensed	Detect property drift between spec and live portal
hubspot.snapshot.create	[READ]	Licensed	Capture CRM state (schema, props, counts)
hubspot.snapshot.diff	[ANALYZE]	Licensed	Compare two snapshots, show what changed

Tier 3: Mutate

Tool	Impact	License	What it does
hubspot.objects.upsert	[WRITE]	Licensed	Bulk upsert from CSV (dry-run default, two-phase apply)
hubspot.dedupe.apply	[MERGE]	Licensed	Execute a merge plan (requires plan_hash verification)

The free tools are the strongest hooks: pull past 10k records and generate dedup merge plans — no account needed. The paywall appears when you act on what you found (upsert, apply merges, snapshots).

Safety model

All mutations use two-phase confirmation:

1. Dry-run (default): tool runs without making changes, returns a preview + plan_hash
2. Apply: caller passes apply=true AND the plan_hash from step 1. If the hash doesn't match (plan changed, wrong file), the tool rejects with a clear error.

Every tool response includes an impact classification: [READ], [ANALYZE], [WRITE], or [MERGE].

Response envelope

Every tool returns a consistent GremlinMCPResponse/v1 JSON:

{
  "$schema": "GremlinMCPResponse/v1",
  "ok": true,
  "summary": "Pulled 47,231 contacts across 12 auto-window queries",
  "data": { ... },
  "artifact": { "type": "file", "path": "...", "row_count": 47231 },
  "warnings": [],
  "safety": { "dry_run": false, "impact": "read" },
  "raw": { "agentic_result": { ... }, "exit_code": 0 }
}

Auth

This MCP server never stores tokens. It delegates to g-gremlin's credential chain:

1. G_GREMLIN_HUBSPOT_ACCESS_TOKEN env var (highest priority)
2. g-gremlin hubspot connect --access-token <PAT> (stored locally in ~/.g_gremlin/)
3. g-gremlin hubspot oauth connect (browser-based OAuth)

Troubleshooting

"HubSpot not configured" error in Claude Desktop?

Claude Desktop may run under a different user context than your terminal. Set the token in the MCP config's env block (see Quickstart above) or set G_GREMLIN_HUBSPOT_ACCESS_TOKEN as a system-level environment variable.

Known gaps & roadmap

This is a public beta. Core read and analyze workflows are stable. Known gaps:

• Remote MCP (SSE transport) — currently stdio only; SSE/streamable HTTP planned for teams that don't want local installs
• Workflow diffing — g-gremlin has workflow comparison commands, not yet exposed as MCP tools
• Association management — create/delete associations between objects
• List management — HubSpot list creation and membership management
• Pipeline management — deal/ticket pipeline configuration

Found a bug or have a feature request? Open an issue.

Requires

• Python 3.10+
• g-gremlin >= 0.1.14 (version checked at startup)
• A HubSpot Private App token with CRM scopes

Development

git clone https://github.com/mikeheilmann1024/g-gremlin-hubspot-mcp
cd g-gremlin-hubspot-mcp
pip install -e ".[dev]"
pytest

License

MIT