Overview
The HubSpot MCP server implements the Model Context Protocol to let AI assistants query and modify your HubSpot CRM. Instead of alt-tabbing to HubSpot to look up a contact or check a deal stage, you ask your AI tool directly. It calls HubSpot's API through the MCP server and returns structured data.
HubSpot launched its official remote MCP server in public beta on September 1, 2025. Community-built servers have been available since early 2025. Both approaches give AI agents access to contacts, companies, deals, tickets, and more, but they differ in authentication, write access, and hosting.
Official vs Community Servers
Two categories exist. Understanding the tradeoffs upfront saves setup time.
| HubSpot Official (Remote) | Community (Local) | |
|---|---|---|
| Hosting | Cloud (mcp.hubspot.com) | Self-hosted (Node.js) |
| Authentication | OAuth 2.1 with PKCE | Private app access token |
| Read Access | 12 CRM object types | Contacts, companies, deals, engagements |
| Write Access | Read-only | Full CRUD (create, read, update) |
| Setup Complexity | Low (no code to deploy) | Medium (clone, build, configure) |
| Custom Objects | No | Depends on implementation |
| Delete Operations | No | No (most implementations) |
| Maintenance | HubSpot-managed | You maintain |
| Cost | Free (HubSpot account required) | Free (open source) |
Which to choose
- Official remote server: You only need to read CRM data. You want zero infrastructure. You use Claude.ai with a paid Anthropic plan.
- Community local server: You need to create contacts, update deals, or log engagements. You use Claude Code, Cursor, or another MCP client. You want full control over the server.
Supported Tools
Community MCP servers (like v4lheru/hubspot-mcp) expose 16 tools across four categories. The official remote server provides similar read operations but no writes.
Contact Management
| Tool | Description |
|---|---|
| hubspot_create_contact | Create a new contact with duplicate prevention |
| hubspot_get_contact | Fetch contact details by ID |
| hubspot_find_contact_by_email | Look up a contact by email address |
| hubspot_find_contact_by_name | Search by name with optional company filter |
| hubspot_get_recent_contacts | List recently modified contacts |
Company Management
| Tool | Description |
|---|---|
| hubspot_create_company | Create a new company record |
| hubspot_get_company | Fetch company details by ID |
| hubspot_find_company_by_name | Search companies by name |
| hubspot_find_company_by_domain | Look up a company by its website domain |
| hubspot_get_company_activity | Retrieve engagement history for a company |
| hubspot_get_recent_companies | List recently active companies |
Deal Management
| Tool | Description |
|---|---|
| hubspot_create_deal | Create a new deal in your pipeline |
| hubspot_get_deal | Retrieve deal details by ID |
| hubspot_get_recent_deals | List recently modified deals |
Engagement Tracking
| Tool | Description |
|---|---|
| hubspot_get_recent_engagements | View recent activity across all objects |
| hubspot_get_recent_conversations | Retrieve conversation threads with messages |
Setup: Create a HubSpot Private App Token
Community MCP servers authenticate with a HubSpot private app access token. The official remote server uses OAuth 2.1 instead (configured through HubSpot's MCP auth app UI). This section covers the private app approach.
Step 1: Create the Private App
- Log into HubSpot. Go to Settings > Account Setup > Integrations > Private Apps.
- Click Create a private app.
- Name it something like "MCP Server".
Step 2: Configure Scopes
Under the Scopes tab, enable these permissions:
Required API Scopes
crm.objects.contacts.read
crm.objects.contacts.write
crm.objects.companies.read
crm.objects.companies.write
crm.objects.deals.read
crm.objects.deals.write
crm.objects.owners.read
sales-email-read # optional: for conversation historyStep 3: Copy the Access Token
Click Create app, then copy the access token. Store it securely. HubSpot will not show this token again after you leave the page.
Token security
Never commit your access token to version control. Use environment variables or a secrets manager. The token grants full read/write access to your CRM based on the scopes you configured.
Claude Desktop Configuration
Add the HubSpot MCP server to your Claude Desktop config file. On macOS, this is at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows, %APPDATA%\Claude\claude_desktop_config.json.
Option A: Node.js (v4lheru/hubspot-mcp)
claude_desktop_config.json
{
"mcpServers": {
"hubspot": {
"command": "node",
"args": ["/path/to/hubspot-mcp/build/index.js"],
"env": {
"HUBSPOT_ACCESS_TOKEN": "pat-na1-xxxxx"
}
}
}
}Option B: Docker (peakmojo/mcp-hubspot)
claude_desktop_config.json
{
"mcpServers": {
"hubspot": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "HUBSPOT_ACCESS_TOKEN=pat-na1-xxxxx",
"-v", "/path/to/storage:/storage",
"buryhuang/mcp-hubspot:latest"
]
}
}
}The Docker option from peakmojo includes FAISS-based vector storage for semantic search across previously retrieved HubSpot data. Mount a local directory to /storage for persistence between sessions.
Cursor Configuration
In Cursor, go to Settings > Cursor Settings > Tools & MCP. Click Add MCP Server and provide the configuration.
Cursor MCP Settings
Name: hubspot
Type: command
Command: node /path/to/hubspot-mcp/build/index.js
Environment Variables:
HUBSPOT_ACCESS_TOKEN=pat-na1-xxxxxAlternatively, add a .cursor/mcp.json file to your project root:
.cursor/mcp.json
{
"mcpServers": {
"hubspot": {
"command": "node",
"args": ["/path/to/hubspot-mcp/build/index.js"],
"env": {
"HUBSPOT_ACCESS_TOKEN": "pat-na1-xxxxx"
}
}
}
}Claude Code Configuration
Claude Code reads MCP server config from .mcp.json in your project root (project-scoped) or ~/.claude/mcp.json (global). Add the HubSpot server to either file:
.mcp.json
{
"mcpServers": {
"hubspot": {
"command": "node",
"args": ["/path/to/hubspot-mcp/build/index.js"],
"env": {
"HUBSPOT_ACCESS_TOKEN": "pat-na1-xxxxx"
}
}
}
}Once configured, Claude Code discovers the HubSpot tools automatically. You can ask it to look up contacts, create deals, or check company activity directly in your terminal session.
Practical workflow
Combine the HubSpot MCP server with a code search tool like WarpGrep. While building a HubSpot integration, your AI agent can navigate your codebase with semantic search and simultaneously query live CRM data to verify field mappings, check contact properties, or validate deal pipeline stages.
Rate Limits by HubSpot Tier
The MCP server passes requests through to HubSpot's API. Rate limits are determined by your HubSpot subscription, not the MCP server itself.
| HubSpot Tier | Per 10 Seconds | Per Day |
|---|---|---|
| Free / Starter | 100 requests | 250,000 |
| Professional | 190 requests | 625,000 |
| Enterprise | 190 requests | 1,000,000 |
| + API Limit Add-on | 250 requests | +1,000,000 |
For typical MCP usage (a few queries per conversation), even the Free tier is more than sufficient. Rate limits only become relevant if you're running batch operations or automated pipelines that make hundreds of requests in quick succession.
Exceeding the limit returns a 429 error. Community MCP servers like v4lheru/hubspot-mcp include automatic rate limit handling with retry logic. The official remote server handles this on HubSpot's side.
Use Cases
Prospect Research During Outreach
Ask your AI agent to pull a contact's engagement history, recent deals, and company info before drafting an outreach email. No tab switching, no manual CRM lookups.
CRM Data Entry from Code Context
Building a customer integration? Create contact records directly from your editor when you encounter new customer info in code reviews, support tickets, or documentation.
Deal Pipeline Monitoring
Query recent deals and their stages during planning sessions. Get pipeline snapshots, identify stalled deals, and check close dates without opening the HubSpot dashboard.
Integration Development
While building HubSpot integrations, query live CRM data to verify API responses, check property schemas, and validate field mappings. The MCP server and your codebase in the same AI context.
Meeting Prep
Before a sales call, pull the company's activity history, recent ticket submissions, deal stages, and contact details. Have your AI agent summarize the relationship status in seconds.
Engagement Logging
Log calls, meetings, and notes to HubSpot from your AI agent. Capture action items from a conversation and attach them to the right contact or deal record.
Limitations
Current constraints to be aware of
- No delete operations: Neither the official nor most community servers support deleting CRM records. This is a safety measure.
- No custom objects: The official server and most community implementations only support standard HubSpot objects (contacts, companies, deals, tickets, etc.).
- Official server is read-only: HubSpot's remote MCP server at mcp.hubspot.com does not support creating or updating records.
- Bulk limits: The Claude connector caps bulk operations at 10 records per action.
- Sensitive data properties: Custom properties marked as "Sensitive Data" in HubSpot are not accessible through the MCP server.
- No association management: Creating associations between objects (linking a contact to a company) is limited to standard types in most implementations.
These limitations are practical, not fundamental. Community servers can be extended to support additional operations. HubSpot will likely expand the official server's capabilities as the MCP specification matures and OAuth 2.1 rollout completes.
Frequently Asked Questions
What is the HubSpot MCP server?
It implements the Model Context Protocol to connect AI assistants (Claude, Cursor, and other MCP-compatible clients) to your HubSpot CRM. The server translates natural language requests into HubSpot API calls and returns structured CRM data.
Does the official HubSpot MCP server support write operations?
No. HubSpot's remote MCP server at mcp.hubspot.com is read-only. It supports reading 12 CRM object types (contacts, companies, deals, tickets, products, line items, invoices, quotes, subscriptions, orders, carts, users). For write operations, use a community-built server like v4lheru/hubspot-mcp with a private app access token.
What API scopes do I need?
For a community server with full CRUD: crm.objects.contacts.read, crm.objects.contacts.write, crm.objects.companies.read, crm.objects.companies.write, crm.objects.deals.read, crm.objects.deals.write, and crm.objects.owners.read. Add sales-email-read for conversation history.
What are the rate limits?
Rate limits follow your HubSpot subscription tier. Free/Starter: 100 requests per 10 seconds, 250,000 per day. Professional: 190 per 10 seconds, 625,000 per day. Enterprise: 190 per 10 seconds, 1,000,000 per day. For typical AI assistant usage, even Free tier limits are sufficient.
Can I use it with Claude Code?
Yes. Add the server config to .mcp.json in your project root or ~/.claude/mcp.json globally. Point the command to your built server binary and set HUBSPOT_ACCESS_TOKEN as an environment variable. Claude Code picks up the tools automatically.
Related
Semantic Code Search for HubSpot Integrations
Building a HubSpot integration? WarpGrep indexes your codebase and gives AI agents semantic search. Navigate API wrappers, webhook handlers, and CRM sync logic by meaning, not keywords.