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

HubSpot stores your contacts, deals, and pipeline data. Claude Code writes scripts, runs API calls, and automates workflows from the terminal. The claude code hubspot mcp connection bridges the two — giving Claude Code direct, scoped access to your CRM without writing raw HTTP requests.

This guide covers three setup paths, the required scopes and permissions, and practical automation examples you can run today. If you have already connected Claude Code to Salesforce via MCP, the HubSpot setup follows the same pattern — different server, identical workflow.

What Is the HubSpot MCP Server?

The HubSpot MCP server is an implementation of the Model Context Protocol that connects Claude Code to your HubSpot account. MCP is an open standard — created by Anthropic — that lets AI tools call external services through a structured, permission-controlled interface.

Instead of writing curl commands against the HubSpot API, you tell Claude Code "find all deals closing this month over $25,000" and it translates that into the correct API call, executes it, and returns structured results. The MCP layer handles authentication, rate limiting, and response formatting.

Why Use an MCP Server Instead of the REST API?

Claude Code can hit the HubSpot REST API directly — it writes Python or Node.js scripts that send HTTP requests. The MCP approach adds three advantages that matter for daily CRM work.

• No code required per operation. Ask Claude Code "create a contact for Jane Doe at Acme Corp" — the MCP server handles serialization, endpoint routing, and error handling.
• Scoped permissions. You decide which objects Claude Code can read or write. The REST API gives blanket access to anything your token allows. MCP lets you define a narrower surface.
• Session persistence. The MCP connection stays active across your Claude Code session. No need to re-authenticate or re-export tokens for every new command.

The tradeoff: MCP servers abstract away the raw API. If you need custom endpoints, webhooks, or batch operations beyond 10 records, you will still want direct API scripts. For most GTM workflows in Claude Code, the MCP layer is the faster path.

Prerequisites

All three setup paths share the same base requirements. Gather these before starting.

• Claude Code installed — version 1.0+ with MCP support. Run claude --version to verify.
• HubSpot account — Free CRM works for the open-source path. The official connector requires the target account to have App Marketplace permissions.
• Node.js 18+ — Required for the CLI and npm paths. Not needed for the connector.
• HubSpot Super Admin or App Marketplace access — Needed to create Private Apps or authorize the connector. Standard users cannot grant scopes.

Option 1: HubSpot CLI Setup (Official)

The fastest path. HubSpot's own CLI includes a built-in MCP setup command that configures the connection for Claude Code automatically. According to HubSpot's developer documentation, you need CLI version 8.2.0 or higher.

Step 1: Install or Update the HubSpot CLI

# Install globally
npm install -g @hubspot/cli

# Verify version (must be 8.2.0+)
hs --version

Step 2: Run the MCP Setup

hs mcp setup

The CLI prompts you to select which client to configure. Choose Claude Code using the arrow keys and spacebar. It then asks whether to use standalone mode — select yes if global npm installs are restricted on your machine.

Step 3: Verify the Connection

Restart Claude Code after setup. Then run:

# Inside Claude Code, type:
/mcp

# Select "HubSpotDev" from the server list
# Status should show "Connected"

If it shows "Disconnected," re-run hs mcp setup and verify your CLI version.

Option 2: Open-Source MCP Server (npm)

The mcp-hubspot package on GitHub gives you full control over scopes, deployment, and customization. This is the right choice if you want to self-host the server or need access beyond what the official CLI exposes.

Step 1: Create a HubSpot Private App

1. Go to Settings → Integrations → Private Apps in your HubSpot portal.
2. Click Create a private app. Name it something like "Claude Code MCP".
3. Under Scopes, add the CRM permissions you need (see the Scopes section below).
4. Click Create app. Copy the generated access token immediately — HubSpot only shows it once.

Step 2: Install the Server

# Option A: Install via Smithery (auto-configures Claude Code)
npx -y @smithery/cli@latest install mcp-hubspot --client claude

# Option B: Clone and run manually
git clone https://github.com/peakmojo/mcp-hubspot.git
cd mcp-hubspot
npm install

Step 3: Configure the Access Token

Create a .env file in the server directory:

HUBSPOT_ACCESS_TOKEN=pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Step 4: Register the Server With Claude Code

# Start the server
npm start

# In a separate terminal, register with Claude Code
claude mcp add hubspot-crm --transport stdio "npx mcp-hubspot"

# Verify
claude mcp list

The claude mcp list output should show hubspot-crm with status Connected.

Option 3: HubSpot Connector for Claude

The zero-terminal option. HubSpot's official connector runs inside the Claude web interface — no CLI, no npm, no .env files. It is the fastest path for non-technical team members who want CRM data in their Claude conversations.

Requirements

• Paid Anthropic subscription (Pro, Max, Team, or Enterprise)
• HubSpot Super Admin or App Marketplace permissions

Setup Steps

1. Open Claude → Settings → Connectors.
2. Browse connectors and select HubSpot.
3. Click Add to your team, then Connect.
4. Authenticate with your HubSpot account and grant the requested permissions.
5. Return to Claude and test with a query like "list my 5 most recent deals."

Super Admins can grant connector access to other team members via Settings → Integrations → Connected Apps → HubSpot connector → Give users access.

Scopes and Permissions

Scopes control what Claude Code can access and modify. Start with read-only access and add write permissions only for objects you actively update through AI.

For engagement logging (calls, meetings, notes, tasks, emails), add the corresponding engagement scopes. The connector path grants read access to engagements by default — write access requires explicit authorization.

Real-World Automation Examples

Once the MCP connection is active, Claude Code becomes a natural-language interface to your HubSpot CRM. Here are five workflows sales teams run with Claude Code through the HubSpot MCP.

1. Pipeline Health Report

# Prompt to Claude Code:
"Pull all deals in the 'Sales Pipeline' that are closing this month.
Group by stage, show total value per stage, and flag any deal
over $50,000 that hasn't had an activity in the last 14 days."

Claude Code queries the deals object, filters by close date and pipeline, computes the rollup, and checks engagement timestamps — all through MCP tool calls. No script needed.

2. Bulk Contact Update

# Prompt to Claude Code:
"Find all contacts where 'Lead Status' is 'New' and last activity
was more than 30 days ago. Update their status to 'Stale' and add
a note: 'Auto-flagged by Claude Code — no activity in 30+ days.'"

The MCP server handles the search, filter, and batch update. For large lists (100+ contacts), Claude Code automatically pages through results and processes them in 10-record batches.

3. Contact Enrichment Check

# Prompt to Claude Code:
"Find contacts created this week that are missing a phone number
or company name. Export the list as CSV with email, name, and
company fields."

This identifies enrichment gaps that tools like HubSpot enrichment providers or SyncGTM can fill automatically.

4. Deal Stage Automation

# Prompt to Claude Code:
"Move all deals in 'Proposal Sent' stage where the proposal was
sent more than 7 days ago and no meeting is scheduled to
'Needs Follow-Up'. Log a task for each deal owner to follow up
within 48 hours."

Combines deal updates with task creation across two CRM objects — a pattern that normally requires a HubSpot workflow or a custom integration.

5. Account Briefing Generator

# Prompt to Claude Code:
"Pull the full record for Acme Corp — company details, all
associated contacts, open deals, and the last 10 engagement
activities. Summarize into a pre-call briefing I can paste into
Slack."

Claude Code reads across companies, contacts, deals, and engagements in a single session — building context that would take 5+ minutes of manual CRM navigation.

Troubleshooting Common Issues

Enrich HubSpot Records With SyncGTM

The HubSpot MCP server gives Claude Code read/write access to your CRM. SyncGTM adds a layer of automated enrichment on top — filling in missing phone numbers, emails, firmographics, and buying signals without manual effort.

The SyncGTM HubSpot integration connects directly to your portal. When new contacts or companies enter your CRM, SyncGTM runs waterfall enrichment across multiple data providers and writes the best result back to the record. No scripts, no cron jobs, no CSV imports.

• Waterfall phone/email enrichment — 15+ providers checked per record, best match written to HubSpot
• Firmographic fill — revenue, employee count, industry, tech stack appended to company records
• Buying signals — job changes, funding events, hiring surges flagged on matching accounts
• Data hygiene — duplicate detection, email validation, phone formatting standardized

Combine the MCP connection with SyncGTM enrichment: use Claude Code to query and analyze your HubSpot data, and let SyncGTM keep it clean and complete in the background. Explore the top GTM MCPs for Claude Code to see how HubSpot fits into a broader AI-powered GTM stack.

Conclusion

The HubSpot MCP server turns Claude Code into a conversational CRM interface. Three setup paths cover every use case — from the 3-minute connector for ops teams to the fully customizable open-source server for developers.

Start with read-only scopes. Test a few queries against your live data. Once you trust the output, add write access and automate the repetitive CRM tasks that consume hours every week — pipeline reports, stale lead flagging, contact enrichment checks, and engagement logging.

For teams that want enrichment on autopilot, SyncGTM handles the data layer so Claude Code can focus on the analysis and automation layer.