HubSpot MCP Server: AI Agent Integration Guide
HubSpot launched a public beta MCP server enabling Claude and AI agents to read, search, and manage CRM data natively. Setup, use cases, and integration guide.
HubSpot Customer Companies
MCP Tools Available
Public Beta Launch
Compatible With Claude
Key Takeaways
HubSpot quietly launched one of the most consequential CRM features of 2026: a public beta MCP server that lets AI agents like Claude natively read, search, and manage CRM data through natural language. No custom API wrappers, no middleware, no integration platform fees. You install a package, provide a token, and your AI assistant can pull deal pipeline data, search contacts, create notes, and manage tickets as naturally as asking a colleague.
This is significant because it marks the first time a major SaaS platform has adopted the Model Context Protocol (MCP) — Anthropic's open standard for connecting AI models to external tools and data sources. Where previous CRM integrations required developers to build and maintain custom API connections, MCP provides a standardized interface that any compatible AI client can use immediately. For the 228,000+ companies running on HubSpot, this means their CRM data is now accessible through conversational AI without any development work.
What Is HubSpot's MCP Server
The Model Context Protocol is an open standard developed by Anthropic that defines how AI models communicate with external tools and data sources. Think of it as a universal adapter — instead of building separate integrations for Claude, GPT, Gemini, and every other AI model, a service provider builds one MCP server and every MCP-compatible client can connect to it automatically.
HubSpot's MCP server is an npm package (@hubspot/mcp-server) that runs locally on your machine and connects to the HubSpot API using a private app access token. When you configure it with Claude Desktop or Claude Code, Claude can directly interact with your HubSpot instance — searching contacts, reading deal data, creating notes, and managing tickets through natural language requests.
- Write custom API wrapper code
- Handle authentication, pagination, errors
- Build UI or scripts for each workflow
- Maintain code as APIs evolve
- Point-and-click automation builder
- Pre-built triggers and actions
- Monthly subscription costs ($20-300+)
- Limited to predefined workflows
- Natural language queries — no code
- Standardized protocol, works across AI clients
- Free and open-source server
- Flexible, ad-hoc — no workflow limits
Available MCP Tools
HubSpot's MCP server ships with nine tools at launch, covering the core CRM objects that marketing, sales, and service teams interact with daily. Each tool maps to specific HubSpot API endpoints but abstracts away the complexity — you ask Claude what you need, and it selects the appropriate tool automatically.
| Tool | Operations | Required Scope |
|---|---|---|
| Contact Management | Search, read, create, update contacts | crm.objects.contacts |
| Company Records | Search, read, create, update companies | crm.objects.companies |
| Deal Pipeline | Search, read, create, update deals | crm.objects.deals |
| Ticket Handling | Search, read, create, update tickets | tickets |
| Note Creation | Create and attach notes to CRM objects | crm.objects.contacts |
| Engagement Management | Log calls, emails, meetings | crm.objects.contacts |
| CRM Search | Full-text search across all CRM objects | crm.objects.*.read |
| Association Management | Link contacts to companies, deals, tickets | crm.objects.*.read |
| Property Access | Read custom properties and field definitions | crm.schemas.*.read |
The tool set intentionally starts focused. HubSpot is expanding MCP coverage to include marketing email tools, workflow management, and reporting API access in upcoming releases. The initial nine tools cover the objects that teams interact with most frequently and provide the foundation for conversational CRM management.
.read scopes. For full CRM management, add .write scopes. This granular control is essential for enterprise deployments where different team members need different access levels.Setup and Configuration
Getting HubSpot MCP running with Claude takes three steps: create a HubSpot private app, install the MCP server, and configure your AI client. The entire process takes under 10 minutes.
- Navigate to Settings > Integrations > Private Apps in your HubSpot account
- Click Create a private app and give it a descriptive name (e.g., "Claude MCP Integration")
- Under Scopes, select the permissions you need:
crm.objects.contacts.read,crm.objects.deals.read,crm.objects.companies.read, and additional write scopes if needed - Click Create app and copy the generated access token — store it securely
The HubSpot MCP server runs as a local process that bridges your AI client and HubSpot's API. Install it globally or use npx to run it directly:
npm install -g @hubspot/mcp-server
# or run directly with npx
npx @hubspot/mcp-server
Add the HubSpot MCP server to your Claude Desktop configuration file. On macOS, edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"hubspot": {
"command": "npx",
"args": ["@hubspot/mcp-server"],
"env": {
"PRIVATE_APP_ACCESS_TOKEN": "your-token-here"
}
}
}
}
Restart Claude Desktop after saving the configuration. You should see HubSpot listed as an available MCP server in Claude's tool panel.
.claude/settings.json or ~/.claude.json file using the same JSON structure. Claude Code will automatically connect to the HubSpot MCP server when you start a new session. For teams exploring agentic AI workflows, see our agentic AI integration guide.Marketing Team Use Cases
Marketing teams generate and manage the largest volume of contact records in most HubSpot instances. MCP transforms how marketers interact with this data — replacing manual report building and list filtering with natural language queries that return instant answers.
Ask Claude to analyze your contact database and identify high-value leads without building a single report. Example prompts:
- "Find all contacts from companies with 50+ employees who visited our pricing page this month"
- "Show me leads that downloaded our whitepaper but haven't been contacted by sales"
- "Which marketing campaigns generated the most SQLs last quarter?"
Use Claude with MCP to identify incomplete contact records and enrich them based on available data:
- Find contacts missing company associations and suggest matches based on email domains
- Identify duplicate contacts by matching name and email patterns
- Standardize job titles and industry classifications across your database
Instead of navigating HubSpot's reporting dashboard and configuring filters, ask Claude directly: "Compare the conversion rates of our email campaigns from January vs February" or "Which blog posts are generating the most contact form submissions?" Claude queries the CRM data through MCP and returns formatted analysis with actionable insights — no manual report building required.
For teams looking to integrate AI across their entire marketing stack, our AI and digital transformation services can help design workflows that combine MCP-powered CRM access with your broader marketing technology stack.
Sales and Service Use Cases
Sales reps and service agents spend significant time navigating CRM records to prepare for calls, update deal stages, and triage incoming tickets. MCP turns these multi-step, click-heavy processes into single natural language requests.
Sales Workflows
- "Show deals closing this month over $50K"
- "Which deals have been stalled for 30+ days?"
- "Summarize my pipeline by stage with total values"
- "Move the Acme Corp deal to negotiation stage"
- "Give me a full briefing on Acme Corp"
- Pull contact history, deal status, and recent notes
- Identify key stakeholders and decision-makers
- Summarize open tickets or support issues
Service Workflows
- "Show open tickets sorted by priority and age"
- Identify tickets from high-value accounts
- Detect recurring issues across tickets
- Draft initial responses with account context
- "Which tickets are approaching SLA breach?"
- Track average resolution times by category
- Identify bottlenecks in ticket routing
- Generate weekly support performance summaries
MCP vs REST API
MCP and the HubSpot REST API serve fundamentally different purposes. Understanding when to use each prevents teams from either over-relying on MCP for tasks the API handles better, or continuing to write custom API integrations for workflows that MCP now handles in seconds.
| Factor | MCP Server | REST API |
|---|---|---|
| Interface | Natural language | Programmatic (HTTP requests) |
| Best for | Ad-hoc queries, analysis, exploration | Bulk operations, webhooks, automation |
| Setup time | Under 10 minutes | Hours to days (custom code) |
| User skill | Non-technical (natural language) | Developer required |
| Throughput | Single queries, moderate volume | High-volume batch processing |
| Webhooks | Not supported | Full support |
| Custom objects | Not yet supported | Full support |
| Workflow triggers | Not supported | Full support |
| Cost | Free (AI client costs apply) | Free (rate limited) |
When to Use MCP
Use MCP when:
- You need quick answers from CRM data
- The query is ad-hoc and won't recur daily
- Non-technical team members need data access
- You want AI-assisted analysis and summaries
Use REST API when:
- You need bulk data imports or exports
- Workflows must trigger automatically
- You need webhook-driven event processing
- Custom objects or advanced CRM features are required
The smartest approach is using both. MCP handles the conversational, exploratory work — analyzing pipelines, preparing meeting briefs, triaging tickets. The REST API handles the systematic, recurring automation — syncing data, triggering workflows, processing webhooks. They complement each other rather than competing.
Enterprise Considerations
Enterprise deployments require careful attention to security, data privacy, access control, and audit logging. HubSpot's MCP server provides several mechanisms for enterprise governance, but organizations need to establish policies before rolling out access across teams.
- Granular scopes: Create separate private apps for different teams with role-appropriate permissions. Marketing gets read-only contact access; sales gets read-write deal access.
- Token rotation: Rotate private app tokens quarterly. HubSpot supports multiple active tokens per app for zero-downtime rotation.
- Local execution: The MCP server runs on the user's machine — CRM data passes through the user's session, not a third-party cloud service.
- Network restrictions: Enterprise firewalls can restrict MCP server outbound connections to HubSpot API endpoints only.
- GDPR considerations: Data queried through MCP is processed by the AI model. Ensure your AI provider's data processing terms comply with your DPA requirements.
- Data residency: CRM data stays in your HubSpot instance. The MCP server queries data on demand — it does not sync or store data locally.
- PII handling: Restrict MCP access to non-sensitive fields where possible. Use HubSpot's field-level permissions to limit exposure of PII through the API.
- AI model data policies: Claude's API does not train on customer data. Verify equivalent policies if using other AI clients with the HubSpot MCP server.
- HubSpot audit log: All API calls made through MCP are logged in HubSpot's standard API activity log, tagged with the private app name.
- Write operation tracking: Every create and update operation is recorded with timestamp and the private app identifier, providing a full audit trail.
- Rate limit awareness: HubSpot enforces the same API rate limits for MCP as direct API calls — 100 requests per 10 seconds for private apps. Monitor usage to avoid throttling.
.read scopes, deploy to 3-5 power users, and collect feedback for 30 days before expanding access or enabling write operations. This approach minimizes risk while demonstrating value. For enterprise CRM strategy, see our analytics and insights services.Conclusion
HubSpot's MCP server represents a fundamental shift in how teams interact with their CRM. For the first time, non-technical users can query, analyze, and manage CRM data through natural language — no reports to build, no API code to write, no middleware subscriptions to manage. The nine tools available at launch cover the core workflows that marketing, sales, and service teams execute daily, and HubSpot has committed to expanding coverage throughout 2026.
The practical impact is immediate. Sales reps prepare for meetings in 30 seconds instead of 15 minutes. Marketing teams analyze lead quality without waiting for a BI analyst to build a report. Service managers monitor SLA compliance through conversational queries rather than dashboard configurations. And because MCP is an open protocol, the skills and workflows teams build today will transfer to every future platform that adopts the standard.
Ready to Transform Your CRM Workflows?
Whether you're setting up HubSpot MCP for the first time or building enterprise-wide AI-powered CRM workflows, our team can help you implement, optimize, and scale conversational CRM management across your organization.
Frequently Asked Questions
Related Guides
Continue exploring CRM automation and AI-powered business workflows