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

1. 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"
      }
    }
  }
}

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

How it compares

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

Tier 2: Analyze & Plan

Tier 3: Mutate

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