Compiled June 2, 2026. Core findings 25/25 fact-checked (0 refuted) against HubSpot's
own docs/blog/changelog/GitHub; the AI-connector section added from official HubSpot
KB. Sources in SOURCES_INDEX.md.
One-line mental model: The
hsCLI ships code; API tokens move data; AI connectors/MCP let agents (like Claude) do both conversationally. "Automate everything" = use the right one of those three for each job.
1. What the HubSpot CLI (hs) actually is — and isn't
- It's a developer/CMS tool: build & deploy apps, develop CMS themes/modules/ serverless functions, and manage the file-based "Projects" framework with version control. Auth via Personal Access Key (PAK) (recommended) or OAuth2.
- It is NOT a CRM-data tool in the dedicated-command sense — no
hs contacts list. - BUT (verified firsthand on this Mac, CLI v8.8.0):
hs api <endpoint>makes authenticated calls to any PAK-scoped REST endpoint — including CRM. Sohs api /crm/v3/objects/contacts --jsondoes read CRM data. The CLI isn't a CRM product, but it's a perfectly good API client for the audit. - Scope:
hs cms(themes/modules/functions, namespaced since v8.0.0),hs project,hs app,hs hubdb,hs secret,hs sandbox,hs api,hs custom-object,hs mcp.
2. Where CRM data actually flows (not the CLI)
- All HubSpot REST APIs are reached via a private-app access token or public-app OAuth token carrying CRM scopes.
- NEW (Feb 10, 2026): Service Keys — account-level credentials purpose-built for data-only system-to-system integrations (BI tools, warehouses, scripts), meant to replace the legacy private-app-token-paste workflow. Public beta. They do not provide webhooks/UI-extensions/app-pages — those stay in project-based (CLI) apps.
3. The runtime that touches CRM data — deployed by the CLI
- Custom-coded workflow actions (require Data Hub — formerly Operations Hub —
Pro/Enterprise): write JavaScript or Python (beta) that runs on HubSpot-managed
AWS Lambda, calling
@hubspot/api-clientwith a token stored as an encrypted secret (process.env.SECRET_NAME). This is the workhorse for "when X happens in the CRM, do Y." - Project-based serverless functions: packaged in
.functions, support public npm deps, get direct access toPRIVATE_APP_ACCESS_TOKEN. Fully supported again as of platformVersion 2026.03 (config moved toward-hsmeta.json).
4. CI/CD — official HubSpot GitHub Actions
- CMS:
HubSpot/hubspot-cms-deploy-action@v2(GitHub-verified) — deploy CMS on push to main; Git becomes source of truth. - Projects:
HubSpot/hubspot-project-actions(v1.1.0) — composableinstall-hubspot-cli,project-upload,project-deploy,project-validate. - Auth in CI = PAK + account ID via GitHub secrets
(
HUBSPOT_PERSONAL_ACCESS_KEY,HUBSPOT_ACCOUNT_ID).
5. AI agents driving HubSpot — the part that matters most for you ⭐
There are TWO official HubSpot MCP servers + a Claude connector:
- Developer MCP (local) — hs mcp setup (CLI 8.2.0+). Lets AI tools (Claude Code,
Cursor, etc.) scaffold/deploy projects & answer dev-doc questions. Dev workflows only.
- HubSpot MCP server (Remote) — gives any MCP client secure read/write to CRM
data (contacts, deals, engagements). Connect via OAuth at mcp.hubspot.com;
create a user-level app with read scopes for the objects you want.
- HubSpot connector for Claude (official, KB updated Apr 20, 2026) — the easiest
on-ramp. Claude can read your CRM and create/update records, log notes, create
tasks from chat.
- Requirements: HubSpot account + paid Anthropic plan (Pro/Max/Team/Enterprise).
- Safety: set Write tools → Needs Approval so Claude shows changes before acting;
every create/update is in HubSpot's Audit Log, attributed to you + the connector.
- Limits: bulk capped at 10 records at a time; custom validation rules (pipeline
stage / association labels) are not enforced via the connector — mind data integrity.
For you (a CMO already using Claude): the HubSpot connector for Claude is the fastest "automate with AI" win — no code. Use it for the audit too ("fetch 100 deals in stage X, tell me which properties are empty"). Keep writes on Needs Approval.
6. The automation toolkit, mapped to the job
| Job | Right tool |
|---|---|
| Deploy themes/modules/apps from Git | hs CLI + GitHub Actions |
| "When CRM event → do logic" | Custom-coded workflow action (Data Hub Pro/Ent) |
| Push data to a warehouse / BI tool | Service Keys (data-only) |
| Cross-system glue (Slack, sheets, etc.) | iPaaS (Zapier/Make/n8n) (see gap below) |
| AI reads/writes CRM conversationally | HubSpot connector for Claude / Remote MCP |
| Audit the existing implementation | hs api (PAK) or the Claude connector |
Honest gaps (not verified in this pass — treat as open)
The research confirmed the CLI/platform/CI-CD/MCP facts but did not verify:
- iPaaS specifics (Zapier/Make/n8n connectors & auth in 2026) — open.
- Reverse-ETL / warehouse connector details — open.
- Concrete end-to-end CMO/RevOps example workflows — partially (blogs found, not
fact-checked). Vendor-sourced; no independent benchmarking.
- YouTube walkthroughs — candidates found but none survived verification; I ran a
separate transcript pass (see VIDEO_NOTES.md if present / SOURCES_INDEX.md).
Recommended next steps for you
- Try the HubSpot connector for Claude — fastest no-code automation + doubles as an audit tool. Keep writes on Needs-Approval.
- For the implementation audit: authenticate
hswith a read-only PAK (seeHubSpot_CLI_Audit_Ready.md) — I'll inventory objects/properties/pipelines. - For real RevOps automation: custom-coded workflow actions need Data Hub Pro/Enterprise — confirm your subscription tier before planning those.