Claude Code HubSpot MCP: Set Up Your CRM Connection in 2026

This guide covers the complete Claude Code HubSpot MCP setup — from installing the CLI to running your first CRM automation. The HubSpot MCP server gives Claude Code natural language access to your CRM: contacts, deals, companies, activities, and engagement history. Setup takes under 20 minutes.

Most tutorials only cover the happy path. This guide covers the parts that trip people up: choosing the right MCP server for your use case, understanding which OAuth scopes to approve, troubleshooting authentication failures, and structuring automation prompts that actually work in production.

It also covers five real-world automation examples — from bulk contact updates to deal pipeline reporting — so you can start extracting value immediately after setup.

What Is the HubSpot MCP Server?

The HubSpot MCP server is an implementation of the Model Context Protocol standard that gives Claude Code structured, secure access to your HubSpot account. It bridges the gap between Claude's AI capabilities and your live CRM data.

Without MCP, Claude has no access to your HubSpot records. With MCP configured, Claude can execute CRM operations from a single natural language prompt — no API calls, no code, no context switching between tools.

According to HubSpot's developer documentation, the MCP server is part of HubSpot's local development tooling and is configurable for Claude Code, Cursor, VS Code, Codex CLI, Gemini CLI, and Windsurf. This guide focuses specifically on the Claude Code setup.

Which HubSpot MCP Server Should You Use?

There are two distinct HubSpot MCP integrations for Claude. They serve different use cases and have different setup paths.

This guide focuses on the Developer MCP Server— the right choice for Claude Code users who want programmatic CRM access and automation. If you only use Claude.ai's chat interface, the HubSpot Connector for Claude is the simpler option.

Prerequisites

Confirm these before starting. Missing any one of them causes the most common setup failures.

Step 1: Install the HubSpot CLI

If you already have Node.js 18+ and the HubSpot CLI installed, skip to Step 2.

Install Node.js (if needed)

# Check current Node version
node --version

# If below 18, install via nvm (recommended)
nvm install 20
nvm use 20
nvm alias default 20

# Verify
node --version  # Should show v20.x.x

Install the HubSpot CLI

# Install globally via npm
npm install -g @hubspot/cli

# Verify installation
hs --version

# Expected output (version numbers vary):
# @hubspot/cli/6.x.x ...

Verify MCP subcommand availability

Confirm the hs mcp subcommand is available before proceeding. Older CLI versions may not include it.

hs mcp --help

# Expected output shows:
# hs mcp setup       Configure MCP servers
# hs mcp install     Install MCP dependencies

If hs mcp returns “command not found”, update to the latest CLI version: npm install -g @hubspot/cli@latest.

Step 2: Authenticate with HubSpot

The HubSpot MCP server uses the CLI's stored authentication. Set this up before running hs mcp setup.

Initialize the CLI and authenticate

# Initialize the CLI for a HubSpot portal
hs init

# This command will:
# 1. Open your browser to HubSpot OAuth
# 2. Prompt you for a personal access token OR OAuth login
# 3. Ask for your HubSpot portal ID (account ID)
# 4. Store credentials in ~/.hubspot/config.yml

Personal Access Token vs OAuth

HubSpot CLI supports two authentication methods. Use OAuth for interactive developer work. Use a Personal Access Token for automated environments or CI pipelines.

Generate a Personal Access Token (optional)

For non-interactive environments, create a Private App token in HubSpot:

1. Go to HubSpot Settings → Integrations → Private Apps → Create a private app
2. Name the app (e.g., Claude Code MCP)
3. Under Scopes, select the objects Claude needs access to (see Step 4 for scope recommendations)
4. Click Create app and copy the token
5. Authenticate the CLI with the token: hs auth --auth-type personalaccesskey

# Verify authentication
hs accounts list

# Expected output shows your portal name and ID:
# Account Name       | Portal ID | Auth Type
# ───────────────────|───────────|──────────
# My HubSpot Account | 12345678  | personalaccesskey

Step 3: Configure .mcp.json for Claude Code

The fastest path is the built-in hs mcp setup command. It detects Claude Code on your machine and writes the .mcp.json configuration automatically.

Automatic setup via hs mcp setup

# Run from your project directory
hs mcp setup

# Interactive prompts:
# 1. Select clients: [x] Claude Code  [ ] Cursor  [ ] VS Code ...
#    (Use arrow keys to navigate, spacebar to select)
# 2. Choose mode: Standalone (recommended) or Global CLI
# 3. The command writes .mcp.json to your project root

Choose standalone mode unless you want the HubSpot MCP server available globally across all projects. Standalone mode installs the server locally per project — cleaner for team repos where not everyone uses HubSpot.

Manual .mcp.json configuration

If you prefer manual configuration, create .mcp.json in your project root:

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": [
        "-y",
        "@hubspot/mcp-server"
      ]
    }
  }
}

With explicit portal ID

If you work with multiple HubSpot portals, pass the portal ID explicitly to prevent the server from using the wrong account:

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": [
        "-y",
        "@hubspot/mcp-server",
        "--portalId",
        "12345678"
      ]
    }
  }
}

With Personal Access Token via environment variable

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": [
        "-y",
        "@hubspot/mcp-server"
      ],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}

Step 4: Understand OAuth Scopes

HubSpot scopes control exactly what Claude Code can read and write. Approving too few scopes causes MCP tool calls to fail with permission errors. Approving too many creates unnecessary data exposure.

Use the following scope sets as starting points, depending on your use case.

Minimum scope set for RevOps use cases

Extended scopes for full CRM automation

Step 5: Verify the Connection

Start Claude Code from the directory containing your .mcp.json. Claude reads the config on launch and connects to the HubSpot MCP server automatically.

# Launch Claude Code from your project root
claude

Use these four starter prompts to confirm end-to-end connectivity. Each tests a different part of the MCP setup.

Test 1: Verify HubSpot connection

A successful response shows your portal name and ID. This confirms the CLI credential is valid before running data queries.

Test 2: Query recent contacts

Test 3: Query open deals

Test 4: Create a test contact

If all four prompts return correct results, your claude code hubspot mcp setup is complete. Delete the test contact after verification.

For more advanced automation patterns, see top GTM MCPs for Claude Code in 2026 and how GTM teams use Claude Code for revenue operations.

Real-World Automation Examples

These five examples demonstrate what Claude Code can do once connected to HubSpot via MCP. Each is a single natural language prompt that would otherwise require multiple API calls or manual CRM work.

Example 1: Deal pipeline report

This replaces a manual HubSpot report build. Claude queries, groups, and formats the data in one step — useful for Monday morning pipeline reviews.

Example 2: Bulk lifecycle stage update

A complete lifecycle hygiene workflow. Without MCP, this requires a HubSpot workflow, a list, and a manual export. Claude handles it in a single prompt.

Example 3: Meeting activity logging

CRM logging after calls is the most skipped sales task. This prompt takes 10 seconds from a voice transcript or call notes.

Example 4: Contact enrichment from custom properties

This extracts a gap report for your enrichment pipeline. Pair it with SyncGTM's HubSpot integration to auto-fill missing ICP scores and firmographic data.

Example 5: Deal creation from inbound form data

A complete inbound lead-to-deal workflow in one prompt. This is the kind of automation that previously required a custom HubSpot workflow or Zapier chain.

For the full picture of how GTM engineers use Claude Code with CRM and enrichment, see the Claude Code for sales teams guide and the best HubSpot enrichment tools in 2026.

Troubleshooting Common Issues

These are the issues that appear most often during HubSpot MCP setup and how to fix them.

Issue 1: “ENOTFOUND” or connection refused

Claude returns an error when calling any HubSpot MCP tool. This means the MCP server process failed to start or cannot reach the HubSpot API.

Issue 2: “Scope not authorized” errors

Claude gets scope errors when trying to read or write specific objects. The authenticated private app or OAuth token is missing required scopes.

Issue 3: Rate limit errors (429)

HubSpot free accounts are limited to 110 API calls per 10 seconds per portal. Claude Code may hit this during bulk operations.

Issue 4: “hs” not recognized on Windows

After installing @hubspot/cli on Windows, the hs command may not resolve in PowerShell.

# Find npm global bin directory
npm config get prefix

# Add <prefix>in to Windows PATH
# System Properties > Environment Variables > Path > New

Close and reopen all terminal windows after updating PATH. If using Git Bash on Windows, the hs command may need an explicit extension: hs.cmd --version.

Pair With SyncGTM for Enrichment Workflows

The HubSpot MCP server is a read/write tool for existing CRM data. It does not source new contact data from the web or external databases.

If your HubSpot contacts are missing emails, phone numbers, LinkedIn URLs, or firmographic properties — that is an enrichment problem, not an MCP problem. SyncGTM connects to HubSpot and waterfall-enriches every contact and company with data from 50+ providers. See SyncGTM pricing for plans starting at $99/mo.

A practical pattern: use Claude Code with the MCP server to find contacts missing enrichment data (custom properties empty), export the list, run SyncGTM enrichment to fill the gaps, then use MCP again to verify the update landed correctly.

For full details on the integration, see the SyncGTM + HubSpot integration guide. For a comparison of HubSpot enrichment tools that work alongside MCP, see the best HubSpot enrichment tools in 2026.

For GTM engineers building a full MCP stack across multiple tools, the top GTM MCPs for Claude Code covers what to add alongside HubSpot — including Salesforce, Linear, and Slack MCPs.