HubSpot Sales MCP Server

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

About HubSpot Sales API

HubSpot Sales Hub empowers sales teams to work more efficiently with powerful automation, detailed insights, and seamless CRM integration. The Sales API provides comprehensive access to:

• Contact Management: Detailed contact profiles and engagement history
• Deal Pipeline: Opportunity tracking and pipeline management
• Sales Automation: Sequences, templates, and task automation
• Meeting Scheduling: Calendar integration and booking links
• Email Tracking: Open rates, clicks, and engagement metrics
• Call Tracking: VoIP integration and call recording
• Sales Analytics: Performance dashboards and forecasting
• Quote Management: CPQ functionality and document generation

Key Features

• REST API v3: Modern sales operations interface
• CRM Associations: Link contacts, companies, and deals
• Activity Tracking: Automatic logging of all interactions
• Pipeline Customization: Flexible deal stages and properties
• Team Management: Territories, quotas, and permissions
• Document Tracking: Monitor document views and engagement
• Predictive Lead Scoring: AI-powered prioritization
• Conversation Intelligence: Call and meeting insights

What You Can Do with HubSpot Sales MCP Server

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

Contact & Company Management

• Contact Operations

  • "Create contact from business card scan"
  • "Update contact with meeting notes"
  • "Find contacts at specific company"
  • "Merge duplicate contact records"

• Company Intelligence

  • "Enrich company data from domain"
  • "Show all deals for Acme Corp"
  • "Track company engagement score"
  • "Find decision makers at company"

• Relationship Mapping

  • "Map organizational hierarchy"
  • "Identify key stakeholders"
  • "Track buying committee members"
  • "Monitor champion changes"

Deal Management

• Pipeline Operations

  • "Create new deal in qualification stage"
  • "Move deal to negotiation stage"
  • "Update deal amount and close date"
  • "Assign deal to sales rep"

• Deal Intelligence

  • "Show deals closing this month"
  • "Find stalled deals in pipeline"
  • "Calculate weighted pipeline value"
  • "Identify at-risk opportunities"

• Forecasting

  • "Generate sales forecast for Q1"
  • "Track progress against quota"
  • "Predict deal close probability"
  • "Analyze win rate trends"

Sales Communication

• Email Sequences

  • "Enroll contact in follow-up sequence"
  • "Create personalized email template"
  • "Track sequence performance"
  • "Pause sequence for hot leads"

• Email Tracking

  • "Show who opened sales emails"
  • "Track link clicks in proposals"
  • "Monitor email reply rates"
  • "Analyze best send times"

• Meeting Management

  • "Schedule demo with prospect"
  • "Send meeting booking link"
  • "Log meeting notes to CRM"
  • "Track no-show rates"

Call & Activity Tracking

• Call Management

  • "Log call with prospect"
  • "Schedule follow-up call task"
  • "Record call notes and outcome"
  • "Track call duration metrics"

• Task Automation

  • "Create follow-up tasks for team"
  • "Set reminder for contract renewal"
  • "Bulk assign tasks to reps"
  • "Track task completion rates"

• Activity Timeline

  • "Show all touchpoints with contact"
  • "Track engagement history"
  • "Monitor response times"
  • "Analyze activity patterns"

Sales Analytics

• Performance Metrics

  • "Show sales rep leaderboard"
  • "Track activity metrics by rep"
  • "Analyze conversion rates by stage"
  • "Monitor average deal size"

• Pipeline Analytics

  • "Calculate pipeline velocity"
  • "Show bottlenecks in sales process"
  • "Track stage duration"
  • "Analyze drop-off points"

• Revenue Reporting

  • "Generate closed-won report"
  • "Track MRR growth"
  • "Analyze sales by product"
  • "Monitor quota attainment"

Quote & Document Management

• Quote Generation

  • "Create quote for opportunity"
  • "Apply discount to line items"
  • "Set payment terms"
  • "Generate PDF quote"

• Document Tracking

  • "Share proposal with prospect"
  • "Track document views"
  • "Monitor time spent on pages"
  • "Alert when contract opened"

• E-Signature

  • "Send contract for signature"
  • "Track signature status"
  • "Set signing order"
  • "Store signed documents"

Prerequisites

• Access to Cequence AI Gateway
• HubSpot account with Sales Hub
• Sales permissions or Super Admin access
• App creation capabilities in HubSpot

Step 1: Create HubSpot App

1.1 Access HubSpot Developers

1. Navigate to developers.hubspot.com
2. Sign in with your HubSpot account
3. Click Manage apps

1.2 Create New App

1. Click Create app
2. Fill in:
   • App name: "AI Gateway Sales MCP"
   • Description: "MCP server for Sales Hub integration"

1.3 Configure OAuth

1. Navigate to Auth tab
2. Set Redirect URL:

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

3. Select required scopes

1.4 Get Credentials

Copy App ID, Client ID, and Client secret.

Step 2-4: Standard Setup

Follow standard steps to access AI Gateway, find HubSpot Sales API, and create MCP server.

Step 5: Configure API Endpoints

1. Base URL: https://api.hubapi.com
2. Select endpoints for sales operations
3. Click Next

Step 6: MCP Server Configuration

1. Name: "HubSpot Sales Automation"
2. Description: "Sales pipeline and CRM management"
3. Configure production mode
4. Click Next

Step 7: Configure Authentication

Set up OAuth 2.0 with your HubSpot app credentials.

Available HubSpot Sales OAuth Scopes

Core CRM Access

• crm.objects.contacts.read / crm.objects.contacts.write

  • Manage contact records
  • Update properties
  • Track interactions
  • Handle associations

• crm.objects.companies.read / crm.objects.companies.write

  • Company management
  • Data enrichment
  • Hierarchy tracking
  • Property updates

• crm.objects.deals.read / crm.objects.deals.write

  • Deal pipeline management
  • Stage transitions
  • Amount tracking
  • Close date management

Sales Tools

• sales-email-read

  • Read email tracking data
  • Access templates
  • View sequences
  • Monitor engagement

• crm.objects.quotes.read / crm.objects.quotes.write

  • Create quotes
  • Manage line items
  • Apply discounts
  • Generate documents

Communication

• communication-bridge.read / communication-bridge.write
  • Call logging
  • Email integration
  • Meeting tracking
  • Activity timeline

Recommended Scope Combinations

For Core Sales:

crm.objects.contacts.read
crm.objects.contacts.write
crm.objects.companies.read
crm.objects.companies.write
crm.objects.deals.read
crm.objects.deals.write
sales-email-read

For Full Sales Operations:

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.quotes.read
crm.objects.quotes.write
sales-email-read
communication-bridge.read
communication-bridge.write

Step 8-10: Complete Setup

Configure security, choose deployment, and deploy.

Using Your HubSpot Sales MCP Server

With Claude Desktop

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

Natural Language Commands

• "Create deal for new opportunity with Acme Corp"
• "Show all deals closing this quarter"
• "Update contact after discovery call"
• "Generate pipeline forecast report"
• "Start email sequence for cold leads"

API Integration Example

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

// Create contact
const contact = await mcpClient.hubspot.contacts.create({
  email: 'john@example.com',
  firstname: 'John',
  lastname: 'Doe',
  phone: '555-1234',
  company: 'Acme Corp',
  jobtitle: 'VP of Sales'
});

// Create deal
const deal = await mcpClient.hubspot.deals.create({
  dealname: 'Acme Corp - Enterprise Plan',
  amount: 50000,
  closedate: '2025-03-31',
  pipeline: 'default',
  dealstage: 'qualifiedtobuy',
  hubspot_owner_id: 'owner-id'
});

// Associate contact with deal
await mcpClient.hubspot.associations.create({
  fromObjectType: 'contacts',
  fromObjectId: contact.id,
  toObjectType: 'deals',
  toObjectId: deal.id,
  associationType: 'contact_to_deal'
});

// Create task
await mcpClient.hubspot.tasks.create({
  subject: 'Follow up on proposal',
  body: 'Check if they have any questions about pricing',
  hs_task_status: 'NOT_STARTED',
  hs_task_priority: 'HIGH',
  hs_timestamp: Date.now() + 86400000, // Tomorrow
  associations: [{
    to: { id: deal.id },
    types: [{ associationTypeId: 'task_to_deal' }]
  }]
});

// Log activity
await mcpClient.hubspot.engagements.create({
  type: 'NOTE',
  metadata: {
    body: 'Had great discovery call. They need our enterprise features.'
  },
  associations: {
    contactIds: [contact.id],
    dealIds: [deal.id]
  }
});

Common Use Cases

Sales Process Management

• Lead qualification workflows
• Opportunity progression tracking
• Deal velocity optimization
• Win/loss analysis

Sales Productivity

• Email template management
• Sequence automation
• Meeting scheduling
• Task prioritization

Performance Management

• Rep activity tracking
• Quota attainment monitoring
• Coaching insights
• Commission calculation

Security Best Practices

1. OAuth Security:

   • Secure credential storage
   • Token rotation
   • Minimal scope usage
   • Access auditing

2. Data Protection:

   • Field-level permissions
   • Record access control
   • PII handling
   • Activity logging

3. Integration Security:

   • API rate limiting
   • Webhook validation
   • IP restrictions
   • Error handling

Troubleshooting

Common Issues

1. Authentication Errors

   • Verify OAuth token
   • Check scope permissions
   • Refresh expired tokens
   • Validate credentials

2. Data Sync Issues

   • Check property mappings
   • Verify associations
   • Review validation rules
   • Monitor sync logs

3. Performance Issues

   • Implement pagination
   • Use batch operations
   • Cache frequently used data
   • Optimize API calls

Getting Help

• Documentation: AI Gateway Docs
• Support: support@cequence.ai
• HubSpot Docs: developers.hubspot.com

---