Connector Guide

Editor & terminal

VS Code is your editor and your terminal. Everything else in this guide gets done from inside it.

Install VS Code

~5 min

VS Code is the editor and integrated terminal you'll use for the rest of the guide.

Install

Download from code.visualstudio.com and drag the app to Applications.

Download from code.visualstudio.com and run the installer. During install, check Add to PATH and the Open with Code context menu options.

Verify

Open VS Code. You should see the Welcome screen.

Open the integrated terminal

~1 min

Inside VS Code, open the integrated terminal panel — it docks at the bottom of the editor and inherits the folder you have open.

Shortcut (Mac & Windows): Ctrl + ` (backtick), or Terminal → New Terminal from the menu bar.

Terminal cheat sheet

pwd	Print working directory (where am I?)
ls	List files in this directory
cd foldername	Change into a folder
cd ..	Go up one level
cd ~	Go to your home directory
clear	Clear the terminal output

You'll use this terminal for the rest of the guide.

Core tooling

A package manager, Node.js, and Git form the base that everything else installs on top of.

Install a package manager

~5 min

Package managers install other tools cleanly and let you update them later.

Install

Install Homebrew by pasting this into the terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the prompts. The installer may print two PATH commands to add Homebrew to your shell — run them exactly as printed.

winget is built in on modern Windows — nothing to install.

Verify

brew --version

winget --version

If you don't see a version number, update Windows or install App Installer from the Microsoft Store.

Install Node.js

~3 min

Node is needed for the HubSpot CLI and, on Windows, for Claude Code.

Install

brew install node

Do this first — PowerShell execution policy Windows blocks npm and other Node-installed scripts by default, which breaks the HubSpot CLI and Claude Code installs later on. Run this once in your terminal before installing Node:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Then close and reopen the terminal so the new policy takes effect.

winget install OpenJS.NodeJS

Close and reopen VS Code's terminal so it picks up the new PATH.

Verify

node --version prints v18 or higher; npm --version also prints a version.

Install Git

~3 min

Install

brew install git

Or accept the prompt to install Xcode Command Line Tools the first time you run any git command.

winget install Git.Git

Close and reopen the terminal.

Verify

git --version

One-time config

Replace with your real name and work email:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Install Claude Code

Claude Code is the terminal-based coding agent you'll use for the rest of this guide.

Claude Code

~5 min

Install

brew install --cask claude-code

Or, if you'd rather use npm:

npm install -g @anthropic-ai/claude-code

Requires the Node.js install from the Core tooling section above.

Sign in

Start Claude Code:

claude

The first run opens your browser and walks you through signing in with your Claude.ai account. If your organization uses the Claude Console instead, you can set an API key when prompted. Once complete, your credentials are stored securely and reused for future sessions.

Type /exit or press Ctrl+C to leave the interactive prompt at any time.

Verify

claude --version

HubSpot CLI & Developer MCP

Two pieces: the HubSpot CLI to build and deploy apps, and the HubSpot Developer MCP so Claude Code can build them with you.

Install the HubSpot CLI

~5 min

Install

Same command on Mac and Windows:

npm install -g @hubspot/cli

Authenticate

Connect the CLI to a HubSpot account (a sandbox or test account works fine):

hs account auth

The CLI opens a browser to generate a personal access key. Pick the account, copy the key, and paste it back into the terminal. The CLI saves it to a hubspot.config.yml file in the current directory.

Verify

hs --version

And confirm your connected account is listed:

hs accounts list

Set up the HubSpot Developer MCP

~5 min

This MCP lets Claude Code actually build HubSpot apps.

Set up

In the terminal:

hs mcp setup

When prompted:

Select your client(s): use space to select Claude Code (and any others you use), then press Enter
Standalone mode? If you're on a managed laptop with strict npm permissions, choose y. Otherwise N is fine.
If asked to pin a CLI version, leave blank to always use the latest

Restart Claude Code after setup completes.

Reference: developers.hubspot.com/docs/developer-tooling/local-development/mcp-server

Verify

In Claude Code, run /mcp — you should see HubSpotDev listed.

Connect Claude to HubSpot

This gives Claude — on web, desktop, or mobile — direct access to your HubSpot CRM data, so it can answer questions grounded in real records instead of general knowledge. No terminal required.

HubSpot connector

~5 min

Connect

In Claude, go to Settings → Connectors, then click Browse Connectors.
Search for HubSpot and add it.
Back on the Connectors page, click Connect next to HubSpot.
You'll be redirected to log in with your HubSpot credentials and choose the account you want to connect.
Select the permissions you want to allow, then click Connect app.
You'll be redirected back to your Claude chat, ready to go.

Make sure it's turned on Under Search & Tools in a chat, confirm HubSpot is toggled on so Claude can use it.

Verify

In a new Claude chat, ask: "List 3 contacts in my HubSpot account." If it returns real data, you're connected.

Verification — smoke test

Two quick checks that everything from this guide works together.

Claude Code + HubSpot Developer MCP

In the terminal, start Claude Code:

claude

Enter the following prompt:

"What HubSpot developer tools do you have access to right now?"

Setup complete If Claude Code lists HubSpot Developer MCP tools, your build environment is ready.

Claude + HubSpot connector

In a Claude chat (web, desktop, or mobile), enter:

"Summarize the most recently created contact in my HubSpot account."

Setup complete If the prompt returns a real contact, your connector is ready.

Try it: put your setup to work

Your environment is verified. Now let's do something with it — this takes 5–10 minutes and gives you a feel for what a connected agent can do compared to a generic chatbot.

Exercise 1 — Pull from your CRM

In a Claude chat, paste this prompt:

"Use HubSpot to pull the contact record for someone at [pick a company you know]. Summarize what you find in 3 bullets."

This is the difference between a generic chatbot and an agent with a connector — it's pulling from your CRM in real time, not making things up.

Exercise 2 — Draft something real

Follow up with:

"Based on what you found, draft a short follow-up email to that contact. Keep it under 4 sentences."

Claude uses context from the previous step — the actual CRM record — to write something grounded in real data, not generic filler.

Exercise 3 — See what's connected

Open Settings → Connectors in Claude and find HubSpot in the list. That live connection is what just gave Claude real, current access to your CRM instead of relying on general knowledge.

Troubleshooting

"command not found" error

Close and reopen the terminal to apply the updated PATH. On macOS, make sure you ran any PATH-export commands printed by the installer.

npm permission errors (EACCES) on macOS

Do not use sudo. Configure npm to install global packages under your home directory per the npm docs, or use the HubSpot CLI standalone mode described above.

MCP connects but tools fail

Typically an auth issue. Re-run the sign-in or OAuth flow for the affected MCP. If tokens are cached, restart Claude Code.

Claude Code doesn't detect a newly connected MCP

Restart Claude Code. MCP servers are initialized at startup.

Windows: "npm install -g" permission errors

Open the terminal as Administrator for the install, or configure the npm prefix to a directory you own.

Claude's HubSpot connector isn't returning data

Double-check that HubSpot is toggled on under Search & Tools in your chat, and that you granted the permissions it needs when you connected it. If it's still not working, disconnect and reconnect from Settings → Connectors.

If you hit something else, reach out to your HubSpot contact.