HubSpot Integration

Der HubSpot MCP-Server ermöglicht die nahtlose Integration mit Deinem HubSpot CRM. Verwalte Kontakte, Unternehmen, Tickets und greife auf Konversationen zu – alles direkt aus Deinem Assistenten heraus.

Einrichtung

Voraussetzungen

1. Ein HubSpot-Konto (Professional oder Enterprise)
2. Ein HubSpot Private App Access Token
   • Navigiere zu: Einstellungen → Integrationen → Private Apps
   • Erstelle eine neue Private App
   • Konfiguriere die benötigten Berechtigungen (siehe unten)

Benötigte Berechtigungen (Scopes)

CRM-Berechtigungen:

• crm.objects.companies.read – Unternehmen lesen
• crm.objects.companies.write – Unternehmen erstellen/aktualisieren
• crm.objects.contacts.read – Kontakte lesen
• crm.objects.contacts.write – Kontakte erstellen/aktualisieren
• crm.objects.deals.read – Deals lesen (für Engagements)
• crm.objects.deals.write – Deals schreiben (für Engagements)
• crm.objects.owners.read – Eigentümer-Informationen lesen

Weitere Berechtigungen:

• conversations.read – Konversationen und Nachrichten lesen
• conversations.write – Konversationen erstellen (optional)
• tickets – Vollzugriff auf Tickets
• timeline – Zugriff auf Timeline-Events und Engagements

Konfiguration

Der Server benötigt Ihren HubSpot Access Token als Header:

• Header-Name: X-HubSpot-Access-Token
• Header-Wert: Ihr Private App Access Token

⚠️ Wichtig: Der Token wird nur einmal bei der Erstellung angezeigt. Speichere ihn sicher!

Hauptfunktionen

Unternehmensmanagement

• hubspot_create_company: Erstellt ein neues Unternehmen mit Name, Domain und weiteren Eigenschaften
• hubspot_get_company_activity: Zeigt die Aktivitätshistorie eines Unternehmens
• hubspot_get_active_companies: Listet kürzlich aktive Unternehmen auf

Kontaktmanagement

• hubspot_create_contact: Erstellt einen neuen Kontakt mit E-Mail, Namen und weiteren Details
• hubspot_get_active_contacts: Zeigt kürzlich aktive Kontakte an

Konversationen

• hubspot_get_recent_conversations: Ruft aktuelle Konversations-Threads mit Nachrichten ab
  • Unterstützt Filterung nach Zeitraum
  • Inkludiert vollständige Nachrichtenhistorie

Ticketverwaltung

• hubspot_get_tickets: Listet Tickets mit umfangreichen Filteroptionen
  • Filter nach Status, Priorität, Pipeline
  • Sortierung und Paginierung
• hubspot_get_ticket_conversation_threads: Zeigt alle Konversationen zu einem spezifischen Ticket

Verwendungsbeispiele

Neuen Kontakt erstellen

Erstelle einen neuen Kontakt in HubSpot:
- E-Mail: max.mustermann@beispiel.de
- Vorname: Max
- Nachname: Mustermann
- Unternehmen: Beispiel GmbH

Unternehmen mit Aktivitäten abrufen

Zeige mir die letzten Aktivitäten der Firma "Beispiel GmbH" in HubSpot

Offene Support-Tickets anzeigen

Liste alle offenen Support-Tickets mit hoher Priorität auf

Konversationen durchsuchen

Zeige mir alle Konversationen der letzten 7 Tage

Best Practices

Sicherheit

1. Token-Verwaltung: Speichere Deinen Access Token niemals im Code
2. Regelmäßige Rotation: Erneuere Tokens regelmäßig
3. Minimale Berechtigungen: Aktiviere nur benötigte Scopes
4. Aktivitätsüberwachung: Prüfe regelmäßig die App-Logs in HubSpot

Performance

• Nutze Paginierung für große Datenmengen
• Implementiere Caching für häufig abgerufene Daten
• Beachte HubSpots API-Rate-Limits (100 Requests/10 Sekunden)

Datenqualität

• Validiere E-Mail-Adressen vor dem Erstellen von Kontakten
• Nutze aussagekräftige Ticket-Beschreibungen
• Halte Unternehmens- und Kontaktdaten aktuell

Fehlerbehebung

Häufige Fehler

401 Unauthorized

• Überprüfe, ob der Access Token korrekt ist
• Stelle sicher, dass der Token nicht widerrufen wurde
• Verifiziere den Header-Namen: X-HubSpot-Access-Token

403 Forbidden

• Prüfe die konfigurierten Scopes Deiner Private App
• Einige Operationen erfordern zusätzliche Berechtigungen

429 Rate Limit Exceeded

• Implementiere exponentielles Backoff
• Reduziere die Anzahl der Requests
• Nutze Batch-Operationen wo möglich

Weiterführende Ressourcen

• HubSpot Private Apps Dokumentation
• HubSpot API Referenz
• HubSpot Academy

Token widerrufen

Falls Du den Zugriff widerrufen musst:

⚠️ Hinweis: Das Widerrufen oder Erneuern des Tokens unterbricht sofort alle bestehenden Integrationen.