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 (for engagements)
• crm.objects.deals.write - Write deals (for engagements)
• crm.objects.owners.read - Read owner information

Additional Permissions:

• conversations.read - Read conversations and messages
• conversations.write - Create conversations (optional)
• tickets - Full access to tickets
• timeline - Access to timeline events and engagements

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

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

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

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.