Chapter 10: HubSpot MCP Server & AI Development Collaboration

10-1　What is MCP (Model Context Protocol)?

Understand standard protocols for AI editors to communicate with external tools.

🔌 Role of MCP

MCP (Model Context Protocol) is an open protocol developed by Anthropic for AI assistants to securely communicate with external tools and data sources. AI can call "Tools" through the MCP server. HubSpot is the official MCP Server (@hubspot/mcp-server) is provided, You can operate, query, and generate code for HubSpot using natural language using AI editors such as Claude Code and Cursor.

When not using MCP	When using MCP
Code by hand while checking the API reference	Just say "Search for contacts"
Check property name and endpoint each time	AI references the portal's actual schema to generate accurate code
Open a separate tool for test execution	Execute the API and check the results directly in the editor
Follow logs manually for debugging	AI automatically analyzes errors and suggests corrections

10-2 MCP Server setup

hs mcp setup Setup can be completed in a few minutes using commands.

📋 Prerequisites

HubSpot CLI v8.0.0 or higher(Requires Node.js 20)
Authenticated HubSpot CLI（hs auth completion)
AI editor: Claude Code, Cursor, VS Code (Copilot)

Terminal — MCP Server setup
# Check CLI version (8.0.0 or higher required)
hs --version

# Set up MCP Server interactively
hs mcp setup

# ─── Dialogue prompt ────────────────────────────────# ? Which AI client do you want to configure?#   ❯ Claude Code#     Cursor#     VS Code## ? Which HubSpot portal do you want to connect?#   ❯ My Portal (12345678)#     Dev Sandbox (87654321)# ─────────────────────────────────────────────────# Completion message example# ✅ MCP Server configured for Claude Code# Config written to: ~/.claude/mcp.json

Configuration files generated by setup: hs mcp setup automatically writes MCP Server connection information to each AI client's configuration file. For Claude Code ~/.claude/mcp.json, For Cursor ~/.cursor/mcp.json, For VS Code .vscode/mcp.json(per project).

~/.claude/mcp.json — Example generated configuration

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

Terminal — MCP Server operation check
# Start MCP Server manually and test
npx @hubspot/mcp-server

# ✅ HubSpot MCP Server started# Listening for MCP connections...# Connected to portal: My Portal (12345678)# Available tools: 47 tools loaded# Start by specifying a specific portal
HUBSPOT_ACCESS_TOKEN=pat-na1-xxx npx @hubspot/mcp-server
    

10-3 List of available MCP tools

Understand the tools that HubSpot MCP Server provides (the operations that AI can call).

category	Tool example	explanation
CRM	`crm_search_contacts`	Search and filter contacts
	`crm_create_contact`	Create contact
	`crm_get_deals`	Get list of deals
	`crm_update_deal`	Update opportunity properties
schema	`get_schemas`	Schema list of all objects
	`get_properties`	List of properties of specified object
	`create_property`	Create custom property
CMS	`get_blog_posts`	Get blog article list
CMS	`get_hubdb_tables`	HubDB table list and structure
workflow	`list_workflows`	Workflow list
workflow	`get_workflow_details`	Workflow details and execution history
Analytics	`get_analytics_summary`	Page view/conversion tally
Analytics	`get_email_stats`	Email open/click rate

10-4　Cooperation practice with Claude Code

Learn the specific flow of developing while interacting with AI using HubSpot MCP with Claude Code.

🚀 Start Claude Code and check MCP connection

at the terminal claude Execute the command and Claude Code will start. When you start it in your project directory, it automatically loads the context for that codebase as well. If your MCP Server is configured correctly, you should see "HubSpot tools available."

Actual prompt example — schema confirmation

List all custom objects for this portal and Please also tell me the property name and type of each.

Practical prompt examples — data exploration

Of the contacts created last week (March 3-9, 2026), Search for the life cycle stage "lead", Please summarize the number of emails for each email domain.

Actual prompt example — code generation

After checking the schema of this portal's "subscriptions" custom object, Get all records with status "trial" and renewal_date up to the end of this month, Please write a Node.js script to output to CSV. Please generate accurate code using actual property names.

Terminal — Basic usage of Claude Code
# start in project directory
cd ~/projects/hubspot-app
claude

# Start with a specific file in the context
claude --context ./src/sync.js

# Execute only once and finish (automatic execution with CI/CD, etc.)
claude --print "Output all properties of the HubSpot contacts object as JSON"

# Check usage status of MCP tool
claude --mcp-debug
    

Practical prompt examples — debugging aids

In the processEvent function of src/webhook-handler.js, deal.propertyChange event is not being handled correctly. Check out the list of properties for this portal's deal object. Find out the exact value of dealstage (e.g. closedwon), Please identify where the problem is in your code.

10-5 Linkage settings with Cursor

Configuration and usage patterns for using HubSpot MCP with Cursor IDE.

~/.cursor/mcp.json — Settings for Cursor

{
  "mcpServers": {
    "hubspot": {
      "command": "npx",
      "args": ["@hubspot/mcp-server"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "${env:HUBSPOT_ACCESS_TOKEN}",
        "HUBSPOT_PORTAL_ID":    "${env:HUBSPOT_PORTAL_ID}"
      }
    }
  }
}
    

Reference environment variables: In the Cursor settings ${env:変数名} You can refer to system environment variables in the format: It is more secure than writing the token directly to the file..env files and direnv When combined with , it is easy to switch between development environments.

💡Usage patterns with Cursor

Cmd + K (inline code generation):In the code, write "//TODO: Get all deals closed in the past 30 days in HubSpot" and implement it as is with Cmd+K.

Cursor Chat (@ reference MCP tools):In the chat, say "Check out the contact schema and design this data model with @hubspot"

Composer (automatic editing of multiple files):"Create a migration script that adds the seat_count property to the subscriptions custom object and also update the README."

10-6 Implementation of AI-driven development flow

Experience the typical workflow of HubSpot development with MCP.

1

Let AI understand the current status of the portal I asked them to "examine this portal's custom objects, property structure, and workflow, and summarize the current CRM design." AI captures and analyzes the actual schema with MCP tools.
2

Communicating requirements verbally "I want to sync subscription data from Stripe to the subscriptions custom object every day. Please suggest the best way to implement it."
3

Have the code generated with the actual property name AI checks the schema with MCP tools and generates code with accurate property names, types, and API paths. Zero time to look up documentation.
4

Operation check on the spot I asked him to "Run the script you just generated in the sandbox and check the results." The AI actually calls the API, checks the response, and fixes any problems.
5

Also generates test cases and documentation I asked him to write a unit test and a README section for this script. Complete implementation, testing, and documentation all at once.

Practical prompt examples — complete development tasks

Please:1. Check all properties of this portal's "subscriptions" custom object2. Search for records where status is "trial" and renewal_date is until the end of March 20263. To send a “Trial Expiration Alert” email to the contacts of the found records.Present a design proposal for HubSpot Workflow4. Create a contact property update script to trigger the workflow Save the code to src/trial-alert.js.

⚠ Be careful of incorrect operations on the production portal: Because the AI calls the actual API through the MCP tool,Instant writing and deletion of production datawill be done. During development, always use the sandbox portal token. Carefully review any changes to your production portal before making them.

10-7 MCP settings for multiple portals

Switch between multiple portals for development, staging, and production using MCP.

~/.claude/mcp.json — Multiple portal settings

{
  "mcpServers": {
    "hubspot-dev": {
      "command": "npx",
      "args": ["@hubspot/mcp-server"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "pat-na1-dev-token",
        "HUBSPOT_PORTAL_ID":    "11111111"
      }
    },
    "hubspot-staging": {
      "command": "npx",
      "args": ["@hubspot/mcp-server"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "pat-na1-staging-token",
        "HUBSPOT_PORTAL_ID":    "22222222"
      }
    },
    "hubspot-prod": {
      "command": "npx",
      "args": ["@hubspot/mcp-server"],
      "env": {
        "HUBSPOT_ACCESS_TOKEN": "pat-na1-prod-token",
        "HUBSPOT_PORTAL_ID":    "33333333"
      }
    }
  }
}
    

Specification when using: In Claude Code, things like "@hubspot-dev..." and "Check the schema of @hubspot-prod" You can specify the portal to use by @mentioning the server name.

10-8 Summary of this chapter

✅ Chapter 10 Checklist

Understand the role of MCP (Model Context Protocol) and the positioning of HubSpot MCP Server
hs mcp setup MCP can be set for Claude Code / Cursor / VS Code with command
Understood the structure of the generated mcp.json
Understood the types of tools provided by HubSpot MCP Server (CRM, schema, CMS, workflow)
You can perform portal schema queries, data searches, and code generation using natural language.
You can practice the AI-driven development flow of "schema confirmation → requirements communication → code generation → operation confirmation"
Multiple portals for development and production can be managed with mcp.json
Understand the risks of erroneous operations on the production portal and be able to develop with sandbox priority.

About the next chapter (Chapter 11):Learn about security, performance, and production operations. We will explain practical knowledge for safely and stably operating a production environment, such as token management, rate limit measures, error handling, and monitoring design.

HubSpot MCP Server &AI development collaboration

🔌 Role of MCP

✅ Chapter 10 Checklist

HubSpot MCP Server &
AI development collaboration