Setting Up Claude Code for HubSpot: A RevOps Practitioner's Guide

The MCP connector and the Claude chat interface are fine for summarizing a contact record or drafting a follow-up. They aren't what you reach for when you need to audit 50,000 contacts, rebuild a property architecture, or generate a data quality report across an entire portal.

That's what Claude Code is for. It runs in your terminal, talks to the HubSpot API directly, writes and runs its own scripts, and gives you a real working surface for the kind of RevOps work that used to take a developer.

This is our internal training piece on how to set it up safely. Same setup we use in client work. Read it as a practitioner's guide, not a marketing piece.

Short version: Claude Code is a command-line tool that lets an AI agent write and run scripts against the HubSpot API on your behalf. The right setup is: install the CLI, create a dedicated folder per client account, use a read-only service key in production, do all write operations in a sandbox first, and treat the AI's output as a draft a human reviews. The unsafe path is to give it write access to a live portal and trust the first answer.

If you'd rather watch the walkthrough than read it:

Why this matters: probabilistic AI vs deterministic output

Before any commands, the mental model.

AI models are probabilistic. They predict the next token. Two runs of the same prompt against the same data won't necessarily produce the same output. That's fine when you want a draft of an email. It's a problem when you want to know exactly which contacts have a malformed email field, exactly which deals are missing an owner, exactly which workflows are firing on the wrong trigger.

The fix is to use the AI to write code, then run the code, then verify the output of the code. The code is deterministic. Run it twice, get the same result. The AI's job is to translate "find every contact created in the last 90 days with no associated company" into a script. The script's job is to actually run against the API and return the same numbers every time.

That's the loop. You stay in it. AI for translation. Code for execution. Excel sheet or Word doc for the human review at the end. The further you drift from that loop (letting the AI just freelance against the API), the worse your results get on larger data sets, because hallucinations compound.

Everything below is built around that loop.

The three-tier safety model

This is the framework we use on every client engagement. It applies whether you're using Claude Code, n8n, custom Python, or any other agent against a live HubSpot portal.

Tier 1: Read-only production. Your very first interaction with any client portal is read-only. The service key has zero write scopes. Claude Code can pull schemas, export records, summarize property usage, surface data quality issues, audit workflows, and build reports. It cannot change a single thing. Most of the real diagnostic value is unlocked at this tier.

Tier 2: Sandbox writes. When you're ready to actually build something (a new property, a workflow change, a property reorg), you do it in the client's HubSpot sandbox. Same logic and same architecture you'll eventually deploy, but isolated from production. You test heavily. You verify by hand. You let the change sit and observe.

Tier 3: Managed migration to production. Once the sandbox version is proven, the move to production happens through deliberate channels: a copy-paste of the configuration done manually, a controlled deployment script you've reviewed line by line, or a HubSpot-native portal sync. Never an unattended AI run against the live portal. The agent's job ends at sandbox validation.

Skip this model and you'll eventually delete the wrong association label across 12,000 records. We've cleaned up that mistake from other consultants more than once. Build the discipline in from day one.

Installing Claude Code

You'll work in a terminal. On Mac that's Terminal, iTerm, or Warp. On Windows that's PowerShell or Windows Terminal. Pick one and open it.

On Mac (Homebrew):

brew install --cask claude-code

On Mac (curl):

If you don't have Homebrew, the official install script from Anthropic works on any Mac. Search "install Claude Code CLI" and copy the curl command from Anthropic's docs. We won't paste the full command here because it changes; use the official source.

On Windows (PowerShell):

PowerShell has an irm (Invoke-RestMethod) installer pattern. Again, get the exact command from Anthropic's docs rather than copying from a third-party site. Anthropic updates the installer occasionally.

Verify the install worked:

claude --version

If you see a version number, you're good. If you don't, your PATH may not have picked up the install location. A new terminal window usually fixes it.

Launching Claude Code (and the permissions question)

The base command is just:

claude

That launches the interactive session. The first time you run it, it'll open a browser window for authentication. Log in with the email associated with your Claude subscription. Once that's done, you're back in the terminal with a live session.

There's a flag you'll see a lot in our team's commands:

claude --dangerously-skip-permissions

This bypasses the permission prompt that asks you to approve each tool call (file reads, shell commands, network requests). Faster to work in, riskier if you don't know what's running. We use it because we operate in scoped folders and we know what we're authorizing. Don't use it on your first few sessions. Run with permissions on, watch what the agent wants to do, and only switch the flag on once you've built intuition for what's normal.

If you want to pick up where you left off in an earlier session:

claude --resume --dangerously-skip-permissions

That brings up a list of your previous conversations from the current folder. Pick one and you're back in context. This is one of the most useful patterns: long-running engagements live as resumable threads, scoped to a folder.

Folder structure: one client, one folder

This is the part nobody tells you until you've made the mistake of dumping every client into one big Claude folder.

Set up a clean tree:

Claude/
  client-acme/
    .claude/
    notes/
    exports/
  client-globex/
    .claude/
    notes/
    exports/
  myd-internal/
    .claude/

You launch Claude Code from inside the client folder. That folder becomes the agent's working context. It sees the files in that folder, it stores its session history there, and crucially, it doesn't get confused about which client's service key is in play.

When you launch a new conversation, the agent inherits the context of the current directory. It can read the local CLAUDE.md if you have one, find local skills, and pick up where prior sessions left off. Spread your work across a single folder and that context becomes useless because everything's mixed together.

This is also where you keep the client's API token (in a .env file inside the folder, never committed to git, never shared in chat).

Building skills before doing real work

Skills are reusable instruction sets for the agent. Think of them as procedures you've documented once that the agent can reach for every time.

Before you do any actual HubSpot work, build a base set of skills. Our team has these pre-built and shared internally. If you're starting fresh, run this prompt the first time you launch Claude Code in a fresh folder:

Do extensive research on everything we'll need to build against the HubSpot API. Cover authentication, scopes, every CRM object, the schemas API, the batch endpoints, search v3, exports, properties, workflows, and reports. Then create skill files and rules for yourself so you can do this work reliably later. Use the official HubSpot developer docs as your source. Review your output at least three times for accuracy before you finish.

Let it run. It'll take a while. When it's done, you have a baseline skill library the agent can call on for every subsequent HubSpot task without re-researching.

The review-three-times instruction is not optional. Every output the agent produces should be re-checked at least twice. Even better: have it re-check against the source it cited. Sloppy first drafts compound into broken scripts.

Getting the HubSpot service key right

A service key is a token that authorizes the agent to call the HubSpot API on behalf of your account. Get it from the HubSpot portal you're working in:

1. Settings (gear icon) → Integrations → Private Apps (called "service keys" in newer portal versions). If you're working in a client portal, the client's admin creates it for you.
2. Click "Create a private app" (or "Create service key").
3. Name it something specific. We use the client name plus "MYD" so the audit log makes sense later.
4. Open the Scopes tab.

Now the part that matters: pick the right scopes.

For read-only production work: Search "read" in the scope filter. Check every read scope that's relevant to the portal. CRM objects (contacts, companies, deals, tickets, custom objects if the portal has them), schemas, files, owners, pipelines, lists, properties, settings, marketing email (read), forms (read), HubDB (read), conversations, and any other read scope you'll need. Also add CRM exports so the agent can pull data in bulk through the official export endpoint instead of paginating one batch at a time.

Watch out for non-read scopes hiding in unrelated sections. Marketing email, forms, and HubDB don't have a separate "read" scope in every tier. They're combined. If you check those boxes, the agent has write access too. That's fine if you trust your prompting discipline and you know the agent's not going to write, but the safer pattern is to operate without them for now and add them only when you specifically need them.

Skip scopes the portal doesn't actually have. If the portal isn't Enterprise, the custom objects scope will error. If the portal doesn't use Listings, skip that one. Mismatched scopes cause auth errors that look like permissions bugs but are actually scope-mismatch bugs.

For sandbox writes: Same exercise in the sandbox. Add write scopes in the sandbox. Never in production.

Once the key is created, copy it. It's shown once. If you lose it, you regenerate it (which invalidates the old one).

Your first real session: storing the token and running an audit

Back in the terminal, inside the client folder, with Claude Code running:

Please securely store this HubSpot token for the [client name] account in a .env file (do not commit it). Then use your skills to give me a full breakdown of the data quality issues that exist in the portal and any property configuration issues you see. Use the batch API where possible. Review your output at least three times. Output the results as structured Excel and Word files in this folder, and link them in the chat when done.

A few things this prompt does right:

• Names the client explicitly. The agent labels the token correctly and references the right context.
• Tells it where to store the token and that the token doesn't go in git.
• Tells it to use its skills (the ones you bootstrapped earlier).
• Asks for the batch API specifically. Single-record loops over a 50,000-contact portal will rate-limit you and burn hours. The batch API does what you want in a fraction of the calls.
• Asks for a deliverable in static format (Excel + Word) so you can review without the agent in the loop.
• Asks for three review passes before delivery.

The agent will write Python or Node scripts, run them against the API, parse the results, format them, and hand you back the audit. That's the loop. You read the static files, decide what to act on, and the next session moves to the next layer.

Extending the approach beyond HubSpot

Nothing in this setup is HubSpot-specific. The same model (CLI agent + scoped credentials + skills + read-only first + sandbox writes + reviewed deliverables) works for Salesforce, Pipedrive, Stripe, ClickUp, Linear, or any API-driven SaaS.

The more context you put into the folder (skills, CLAUDE.md instructions, .env, prior session logs, downloaded schemas), the more the agent can do without re-prompting. Treat the folder as the agent's memory.

If you want a cross-system view (HubSpot data merged with ClickUp tasks, or Stripe invoices joined to HubSpot deals), it's the same setup with the second API token added to the same folder. Read-only on both sides until you're ready to write somewhere.

Frequently asked questions

What's the difference between Claude Code and the Claude chat or MCP connector?

The chat interface and MCP connector are for fast, conversational work. You ask a question, you get an answer, the agent talks to HubSpot through a pre-built bridge. Claude Code is a developer tool. It runs in your terminal, writes its own scripts, runs them locally, manages files in a folder, and talks to any API directly. The chat is a calculator. Claude Code is a workbench.

Do you need to be a developer to use Claude Code with HubSpot?

You need to be technical enough to read a script and judge whether it's doing the right thing. You don't need to write the script yourself. Most of our team's HubSpot work happens through Claude Code without anyone writing code from scratch. The agent writes. The human reviews.

How does using Claude Code for HubSpot compare to the MCP connector?

The MCP connector is good for quick reads inside a chat session. It can't bulk-export, can't delete, can't run multi-step migrations, and can't be scoped down to read-only as precisely as a service key. For serious work, the API-direct route through Claude Code wins on every axis. The connector is a starting point. We do almost all client work through Claude Code now.

What's the safest way to test Claude Code in a HubSpot portal?

Use a read-only service key in production. Build a sandbox in HubSpot (Settings → Account Setup → Sandboxes) and do all writes there. Only move to production through a controlled deployment that a human runs and reviews. Most damage we've cleaned up came from skipping the sandbox step.

Is --dangerously-skip-permissions actually safe to use?

It's safe if you understand what it does and what folder you're in. It skips Claude Code's per-action confirmation prompts. If your folder is scoped to one client and your service key is read-only, the worst the agent can do is run a script that pulls data. If you're in your home directory with write access to your whole machine, you're trusting the agent's judgment on every shell command. Start with the flag off, build intuition, then turn it on for scoped folders.

How do you keep API tokens out of version control?

Store them in a .env file inside the client folder, add .env to your .gitignore, and confirm with git status before committing anything. If a token ever does land in a commit, rotate it immediately in HubSpot rather than trying to scrub it from history.

Can Claude Code execute HubSpot workflows on a schedule?

Not natively. Claude Code is interactive. For scheduled execution, you write the script in Claude Code, then deploy it to a cron job, GitHub Actions, n8n, or a small Vercel scheduled function. The agent helps you build it; the scheduler runs it.

Key takeaways

• Claude Code is a terminal-based AI agent that writes and runs scripts against APIs like HubSpot's, not a chat interface.
• The safe operating model is read-only in production, writes in sandbox only, manual or scripted promotion to production.
• One folder per client account. Folder becomes the agent's working memory, including the service key in a local .env.
• Install with Homebrew on Mac or PowerShell on Windows. Launch with claude, optionally --dangerously-skip-permissions once you trust your folder scope.
• Bootstrap skills before doing real work: have the agent research the HubSpot API once and write itself instructions to reuse.
• When generating a service key, pick every read scope relevant to the portal. Be careful about scopes that aren't read-only (forms, HubDB, marketing email in some tiers).
• Use the batch API. Use static deliverables (Excel, Word). Ask for three review passes on every output.
• The loop is: AI translates intent into code, code runs deterministically, human reviews static output.

If you want to see this approach applied to a real client portal, book a Diagnostic Conversation and we'll walk through how we'd set it up for your environment.

Author: Dan Saavedra is the founder of MergeYourData, a RevOps consulting firm working with professional services firms on HubSpot. The team operates Claude Code against client portals daily as part of standard delivery.