HubSpot CRM MCP Server

Create a powerful Model Context Protocol (MCP) server for HubSpot CRM in minutes with our AI Gateway. This guide walks you through setting up seamless HubSpot integration with enterprise-grade security and instant OAuth authentication.

About HubSpot CRM API

HubSpot is a leading CRM platform that helps over 194,000 companies grow better. The HubSpot API provides comprehensive access to CRM objects, marketing tools, and sales automation:

• CRM Objects: Manage contacts, companies, deals, tickets, and custom objects
• Pipeline Management: Track deals through customizable sales pipelines
• Marketing Tools: Email campaigns, forms, landing pages, and workflows
• Sales Automation: Sequences, templates, meetings, and productivity tools
• Service Hub: Tickets, knowledge base, customer feedback, and SLAs
• Analytics: Reports, dashboards, and attribution
• Integrations: Webhooks, timeline events, and app marketplace
• Custom Properties: Define and manage custom fields across all objects

Key Features

• REST API v3: Modern API with consistent patterns
• GraphQL API: Flexible queries for complex data needs
• Rate Limiting: 100-500 requests per 10 seconds (varies by tier)
• Batch Operations: Process up to 100 records per request
• Associations: Link related objects with typed relationships
• Search API: Full-text and property-based search
• Change Tracking: Audit trails and property history
• OAuth 2.0: Secure authentication with granular scopes

What You Can Do with HubSpot CRM MCP Server

The MCP server transforms HubSpot's API into a natural language interface, enabling AI agents to:

Contact & Company Management

• Smart Contact Operations

  • "Import contacts from the conference attendee list"
  • "Find all contacts who haven't been contacted in 30 days"
  • "Update job titles for contacts at Acme Corp after the reorg"
  • "Merge duplicate contacts with similar email domains"

• Company Intelligence

  • "Enrich company data with industry and employee count"
  • "Find companies without assigned account owners"
  • "Create parent-child relationships for enterprise accounts"
  • "Tag companies by annual revenue tiers"

• Relationship Mapping

  • "Show all contacts associated with active deals"
  • "Map decision makers at target accounts"
  • "Find influencers and champions at each company"
  • "Track contact engagement across all touchpoints"

Deal & Pipeline Management

• Deal Operations

  • "Create deals for all qualified leads from this week"
  • "Move stalled deals to re-engagement stage"
  • "Update deal amounts based on product selections"
  • "Find deals missing next step activities"

• Pipeline Analytics

  • "Calculate pipeline value by sales rep"
  • "Show deals likely to close this quarter"
  • "Identify bottlenecks in the sales process"
  • "Track win rates by lead source"

• Forecasting

  • "Generate weighted pipeline forecast"
  • "Compare actual vs projected revenue"
  • "Analyze deal velocity by stage"
  • "Predict quarter-end attainment"

Marketing Automation

• Campaign Management

  • "Create email campaign for product launch"
  • "Segment contacts by engagement level"
  • "A/B test subject lines for better open rates"
  • "Schedule drip campaigns for new signups"

• Lead Nurturing

  • "Score leads based on behavior and fit"
  • "Route hot leads to sales immediately"
  • "Create nurture tracks by persona"
  • "Re-engage cold leads with targeted content"

• Form & Landing Page Optimization

  • "Analyze form conversion rates"
  • "Create progressive profiling forms"
  • "Test landing page variations"
  • "Track submission sources"

Sales Productivity

• Activity Automation

  • "Log calls and meetings automatically"
  • "Create follow-up tasks for all demos"
  • "Schedule sequences for outbound campaigns"
  • "Track email opens and link clicks"

• Template Management

  • "Create email templates by sales stage"
  • "Personalize outreach at scale"
  • "Share top-performing templates"
  • "Track template effectiveness"

• Meeting Scheduling

  • "Set up round-robin meeting links"
  • "Block calendar for focus time"
  • "Send meeting reminders automatically"
  • "Track no-show rates by contact"

Service & Support

• Ticket Management

  • "Create support tickets from email"
  • "Route tickets by product and priority"
  • "Escalate overdue tickets automatically"
  • "Track SLA compliance"

• Customer Success

  • "Monitor customer health scores"
  • "Identify upsell opportunities"
  • "Track product usage by account"
  • "Schedule quarterly business reviews"

• Knowledge Base

  • "Create articles from resolved tickets"
  • "Track article effectiveness"
  • "Suggest relevant content to customers"
  • "Update outdated documentation"

Analytics & Reporting

• Performance Dashboards

  • "Create executive dashboard with key metrics"
  • "Track team performance against quotas"
  • "Monitor marketing ROI by channel"
  • "Analyze customer acquisition costs"

• Attribution Analysis

  • "Track multi-touch attribution"
  • "Measure campaign influence on revenue"
  • "Identify most effective lead sources"
  • "Calculate customer lifetime value"

Prerequisites

• Access to Cequence AI Gateway
• HubSpot account (any tier with API access)
• Super Admin or App Developer permissions
• Ability to create private apps or OAuth apps

Step 1: Create HubSpot App

Before setting up the MCP server, you need to create a HubSpot app for OAuth authentication.

1.1 Access HubSpot Developer Account

1. Navigate to app.hubspot.com
2. Go to Settings Integrations Private Apps OR
3. Visit developers.hubspot.com for public apps

1.2 Create Private App (Recommended for single account)

1. Click Create a private app

2. Set app details:

   • Name: "AI Gateway MCP Integration"
   • Description: "MCP server for HubSpot automation"

3. Go to Scopes tab

4. Select required scopes (see Available Scopes section)

5. Click Create app

6. Copy the Access Token

1.3 Create Public App (For OAuth flow)

1. In developer account, click Create app

2. Set app info:

   • App name: "AI Gateway HubSpot MCP"
   • App description: Description of integration

3. Go to Auth tab:

   • Add redirect URLs:

     https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback

4. Configure scopes (see Available Scopes section)

5. Note Client ID and Client Secret

1.4 Configure Webhooks (Optional)

1. Go to Webhooks tab
2. Add webhook URL if using real-time events
3. Select events to subscribe to
4. Configure retry policy

Step 2: Access AI Gateway Apps

1. Log in to your Cequence AI Gateway dashboard
2. Navigate to Apps in the left sidebar
3. You'll see the list of available third-party applications

Step 3: Find and Select HubSpot CRM API

1. In the Apps section, browse through the Third-party category
2. Look for HubSpot CRM or use the search function
3. Click on the HubSpot CRM API card to view details

The HubSpot CRM API card shows:

• Number of available endpoints
• Integration capabilities
• Quick description of functionality

Step 4: Create MCP Server

1. Click the Create MCP Server button on the HubSpot CRM API card
2. You'll be redirected to the MCP Server creation wizard

Step 5: Configure API Endpoints

In the App Configuration step:

1. Base URL is pre-filled: https://api.hubapi.com
2. Select API endpoints to expose to your MCP server based on your needs
3. Click Next to proceed

Step 6: MCP Server Basic Setup

Configure your MCP server details:

1. MCP Server Name: Enter a descriptive name

   • Example: "HubSpot CRM Automation"
   • This name will identify your server in the dashboard

2. Description (Optional): Add details about the server's purpose

   • Example: "Automated CRM operations for sales and marketing teams"

3. Production Mode: Toggle based on your needs

   • ON for production environments
   • OFF for development/testing

4. Click Next to continue

Step 7: Configure Authentication

This is where you'll use your HubSpot app credentials:

1. Authentication Type: Select OAuth 2.0

2. Fill in the OAuth configuration:

   • Authorization URL:

     https://app.hubspot.com/oauth/authorize

   • Token URL:

     https://api.hubapi.com/oauth/v1/token

   • Client ID: Paste from HubSpot app
   • Client Secret: Paste from HubSpot app
   • Redirect URI:

     https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback

3. Scopes: Select from the available HubSpot scopes (see next section)

Available HubSpot OAuth Scopes

Configure the appropriate scopes based on your application needs:

CRM Objects

• crm.objects.contacts.read

  • View contact records
  • Access contact properties
  • See contact associations
  • Read contact lists

• crm.objects.contacts.write

  • Create and update contacts
  • Delete contact records
  • Manage contact properties
  • Update associations

• crm.objects.companies.read

  • View company records
  • Access company properties
  • See company associations
  • Read company insights

• crm.objects.companies.write

  • Create and update companies
  • Delete company records
  • Manage company properties
  • Update relationships

• crm.objects.deals.read

  • View deal records
  • Access deal pipelines
  • See deal associations
  • Track deal history

• crm.objects.deals.write

  • Create and update deals
  • Move deals through stages
  • Delete deal records
  • Manage deal properties

Additional Objects

• crm.objects.tickets.read

  • View support tickets
  • Access ticket pipelines
  • See ticket associations

• crm.objects.tickets.write

  • Create and update tickets
  • Manage ticket status
  • Delete tickets

Schema Access

• crm.schemas.contacts.read

  • View contact properties schema
  • Access property groups
  • See property definitions

• crm.schemas.companies.read

  • View company properties schema
  • Access custom properties
  • See property options

• crm.schemas.deals.read

  • View deal properties schema
  • Access pipeline stages
  • See stage properties

Custom Objects

• crm.objects.custom.read

  • Access custom object records
  • View custom object data
  • See associations

• crm.objects.custom.write

  • Create custom object records
  • Update custom objects
  • Manage associations

Recommended Scope Combinations

For Sales Teams:

crm.objects.contacts.read
crm.objects.contacts.write
crm.objects.companies.read
crm.objects.companies.write
crm.objects.deals.read
crm.objects.deals.write

For Marketing Teams:

crm.objects.contacts.read
crm.objects.contacts.write
forms
marketing-emails.read
marketing-emails.write

For Service Teams:

crm.objects.contacts.read
crm.objects.tickets.read
crm.objects.tickets.write
conversations

Step 8: Configure Security

Set up API protection features:

1. API Protection: Toggle ON to enable

   • Protects against bot attacks, DDoS, and threats
   • Monitors for suspicious activity
   • Rate limiting and anomaly detection

2. Protection Features (when enabled):

   • Auto-scaling protection
   • Managed infrastructure
   • Built-in monitoring
   • Zero maintenance required

3. Click Next to continue

Step 9: Choose Deployment Method

Select your deployment preference:

Option A: Deploy to Cequence Cloud (Recommended)

• Fully managed deployment
• Automatic scaling and monitoring
• Built-in high availability
• Features included:
  • Auto-scaling
  • Managed infrastructure
  • Built-in monitoring
  • Zero maintenance

Option B: Deploy with Helm Chart

• Self-managed Kubernetes deployment
• Full control over infrastructure
• Requires:
  • Kubernetes cluster
  • Helm 3.x installed
  • Container registry access

Click Next after selecting your deployment method.

Step 10: Review and Deploy

Review your MCP server configuration:

• MCP Server Name: Your chosen name
• Base URL: https://api.hubapi.com
• Selected Endpoints: Number of endpoints selected
• Authentication: OAuth 2.0 (Configured)
• API Protection: Enabled/Disabled
• Deployment: Cequence Cloud or Helm

Click Create & Deploy to finalize the setup.

Step 11: Post-Deployment Setup

After successful deployment:

1. Note the MCP Server URL provided

2. Test the OAuth flow:

   • Click "Test Connection"
   • You'll be redirected to HubSpot authorization
   • Select HubSpot account to connect
   • Grant requested permissions
   • Confirm successful connection

3. Configure AI Agents:

   • The MCP server is now available for AI agent connections
   • Use the provided server URL in your AI agent configuration

Using Your HubSpot CRM MCP Server

With Claude Desktop

1. Open Claude Desktop settings

2. Add your MCP server:

   {
     "servers": {
       "hubspot": {
         "url": "your-mcp-server-url",
         "auth": {
           "type": "oauth2",
           "client_id": "your-client-id"
         }
       }
     }
   }

3. Start using natural language commands:

   • "Show me all deals closing this month"
   • "Create a contact for John Smith at Acme Corp"
   • "Find companies that haven't been contacted in 60 days"
   • "Update deal stage for all opportunities with signed contracts"
   • "Generate a pipeline report for the sales meeting"

API Integration Example

// Initialize MCP client
const mcpClient = new MCPClient({
  serverUrl: 'your-mcp-server-url',
  auth: {
    type: 'oauth2',
    token: 'user-access-token'
  }
});

// Search contacts
const contacts = await mcpClient.hubspot.crm.contacts.search({
  filterGroups: [{
    filters: [{
      propertyName: 'email',
      operator: 'CONTAINS',
      value: '@acme.com'
    }]
  }],
  properties: ['email', 'firstname', 'lastname', 'company']
});

// Create a deal
const deal = await mcpClient.hubspot.crm.deals.create({
  properties: {
    dealname: 'New Enterprise Deal',
    amount: '50000',
    dealstage: 'qualifiedtobuy',
    pipeline: 'default',
    closedate: '2025-03-31'
  },
  associations: [{
    to: { id: contactId },
    types: [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 3 }]
  }]
});

// Update multiple companies
await mcpClient.hubspot.crm.companies.batch.update({
  inputs: companies.map(company => ({
    id: company.id,
    properties: {
      lifecyclestage: 'customer',
      annualrevenue: company.revenue
    }
  }))
});

// Create a ticket
const ticket = await mcpClient.hubspot.crm.tickets.create({
  properties: {
    subject: 'Product issue reported',
    content: 'Customer experiencing login problems',
    hs_pipeline_stage: 'new',
    priority: 'HIGH'
  }
});

Common Use Cases

Sales Automation

• Lead scoring and routing
• Deal pipeline management
• Quote generation
• Territory assignment
• Commission tracking

Marketing Operations

• Campaign attribution
• Lead nurturing workflows
• Content personalization
• Event management
• ROI reporting

Customer Success

• Onboarding automation
• Health score tracking
• Renewal management
• Upsell identification
• Churn prevention

Data Management

• Deduplication
• Data enrichment
• Property standardization
• Import/export operations
• Integration syncing

Security Best Practices

1. OAuth Security:

   • Use private apps for single portal
   • Implement token rotation
   • Store credentials securely
   • Monitor API usage

2. Scope Management:

   • Request minimum scopes needed
   • Regular scope audits
   • Use read-only where possible
   • Document scope usage

3. Rate Limit Management:

   • Monitor rate limit headers
   • Implement request queuing
   • Use batch endpoints
   • Cache frequently used data

4. Data Protection:

   • Filter sensitive properties
   • Implement field-level access
   • Audit data exports
   • Follow GDPR compliance

Troubleshooting

Common Issues

1. 401 Unauthorized

   • Check access token validity
   • Verify app installation
   • Ensure scopes are granted
   • Regenerate token if expired

2. 403 Forbidden

   • Check portal permissions
   • Verify object access rights
   • Ensure property visibility
   • Check subscription tier limits

3. 429 Rate Limited

   • Default: 100 requests/10 seconds
   • Check rate limit headers
   • Implement exponential backoff
   • Use batch operations

4. 400 Validation Error

   • Check required properties
   • Validate property values
   • Verify association types
   • Review property options

Getting Help

• Documentation: AI Gateway Docs
• Support: support@cequence.ai
• Community: AI Gateway Forum
• HubSpot API Docs: developers.hubspot.com
• HubSpot Academy: academy.hubspot.com

---