HubSpot Integration

The HubSpot MCP server enables seamless integration with your HubSpot CRM. Manage contacts, companies, tickets and access conversations - all directly from your assistant.

Setup

Prerequisites

1. A HubSpot account (Professional or Enterprise)
2. A HubSpot Private App Access Token
   • Navigate to: Settings → Integrations → Private Apps
   • Create a new Private App
   • Configure the required permissions (see below)

Required Permissions (Scopes)

CRM Permissions:

• crm.objects.companies.read - Read companies
• crm.objects.companies.write - Create/update companies
• crm.objects.contacts.read - Read contacts
• crm.objects.contacts.write - Create/update contacts
• crm.objects.deals.read - Read deals
• crm.objects.deals.write - Create/update deals
• crm.objects.owners.read - Read owner information

Additional Permissions:

• conversations.read - Read conversations and messages
• files - Read/search files and retrieve signed URLs

Optional / Advanced Object Permissions (for generic CRM search):

• sales-email-read (for email object endpoints)
• For other object families (notes, tasks, calls, meetings), check the required scopes in each HubSpot endpoint doc.

Potentially required depending on your HubSpot setup:

• Ticket-related scopes for ticket endpoints (hubspot_get_tickets, hubspot_get_ticket_conversation_threads, pipelines/tickets)

Scope Profiles (When do you need what?)

Method-to-Scope Mapping

Configuration

The server requires your HubSpot Access Token as a header:

• Header Name: X-HubSpot-Access-Token
• Header Value: Your Private App Access Token

⚠️ Important: The token is only shown once during creation. Store it securely!

Main Features

Company Management

• hubspot_create_company: Creates a new company with name, domain and other properties
• hubspot_get_company_activity: Shows the activity history of a company
• hubspot_get_active_companies: Lists recently active companies

Contact Management

• hubspot_create_contact: Creates a new contact with email, name and other details
• hubspot_get_active_contacts: Shows recently active contacts

Generic Search & Retrieve

• hubspot_search_crm_objects: Generic CRM search (contacts, companies, deals, notes, tasks, calls, meetings, emails)
• hubspot_retrieve_crm_object: Retrieve one CRM object by ID including optional associations

File Access

• hubspot_search_files: Search HubSpot files metadata
• hubspot_get_file: Retrieve file metadata and signed URL

Conversations

• hubspot_get_recent_conversations: Retrieves recent conversation threads with messages
  • Supports filtering by time period
  • Includes complete message history

Ticket Management

• hubspot_get_tickets: Lists tickets with extensive filtering options
  • Filter by status, priority, pipeline
  • Sorting and pagination
• hubspot_get_ticket_conversation_threads: Shows all conversations for a specific ticket

Usage Examples

Create New Contact

Create a new contact in HubSpot:
- Email: max.mustermann@example.com
- First Name: Max
- Last Name: Mustermann
- Company: Example GmbH

Retrieve Company with Activities

Show me the recent activities of the company "Example GmbH" in HubSpot

Display Open Support Tickets

List all open support tickets with high priority

Search Conversations

Show me all conversations from the last 7 days

Retrieve CRM Object

Find the latest deal for company "Example GmbH" and return the deal details by ID

Search and Load Files

Search HubSpot files for "invoice" and return the signed download URL of the latest result

Best Practices

Security

1. Token Management: Never store your access token in code
2. Regular Rotation: Renew tokens regularly
3. Minimal Permissions: Only activate required scopes
4. Activity Monitoring: Regularly check app logs in HubSpot

Performance

• Use pagination for large data sets
• Implement caching for frequently accessed data
• Observe HubSpot's API rate limits (100 requests/10 seconds)

Data Quality

• Validate email addresses before creating contacts
• Use meaningful ticket descriptions
• Keep company and contact data up to date

Troubleshooting

Common Errors

401 Unauthorized

• Check if the access token is correct
• Ensure the token hasn't been revoked
• Verify the header name: X-HubSpot-Access-Token

403 Forbidden

• Check the configured scopes of your Private App
• Some operations require additional permissions
• For scope errors, review the connector debug output (requiredScopes) and grant the missing scopes

429 Rate Limit Exceeded

• Implement exponential backoff
• Reduce the number of requests
• Use batch operations where possible

Additional Resources

• HubSpot Private Apps Documentation
• HubSpot API Reference
• HubSpot Academy

Revoking Token

If you need to revoke access:

1. Navigate to: Settings → Integrations → Private Apps
2. Select your app
3. Click "Delete App" or generate a new token

⚠️ Note: Revoking or renewing the token immediately interrupts all existing integrations.