HubSpot Integration

Der HubSpot MCP-Server ermöglicht die nahtlose Integration mit Ihrem HubSpot CRM. Verwalten Sie Kontakte, Unternehmen, Tickets und greifen Sie auf Konversationen zu - alles direkt aus Ihrem Assistenten heraus.

Einrichtung

Voraussetzungen

Ein HubSpot-Konto (Professional oder Enterprise)
Ein HubSpot Private App Access Token
- Navigieren Sie zu: Einstellungen → Integrationen → Private Apps
- Erstellen Sie eine neue Private App
- Konfigurieren Sie 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. Speichern Sie 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

Token-Verwaltung: Speichern Sie Ihren Access Token niemals im Code
Regelmäßige Rotation: Erneuern Sie Tokens regelmäßig
Minimale Berechtigungen: Aktivieren Sie nur benötigte Scopes
Aktivitätsüberwachung: Prüfen Sie regelmäßig die App-Logs in HubSpot

Performance

Nutzen Sie Paginierung für große Datenmengen
Implementieren Sie Caching für häufig abgerufene Daten
Beachten Sie HubSpots API-Rate-Limits (100 Requests/10 Sekunden)

Datenqualität

Validieren Sie E-Mail-Adressen vor dem Erstellen von Kontakten
Nutzen Sie aussagekräftige Ticket-Beschreibungen
Halten Sie Unternehmens- und Kontaktdaten aktuell

Fehlerbehebung

Häufige Fehler

401 Unauthorized

Überprüfen Sie, ob der Access Token korrekt ist
Stellen Sie sicher, dass der Token nicht widerrufen wurde
Verifizieren Sie den Header-Namen: X-HubSpot-Access-Token

403 Forbidden

Prüfen Sie die konfigurierten Scopes Ihrer Private App
Einige Operationen erfordern zusätzliche Berechtigungen

429 Rate Limit Exceeded

Implementieren Sie exponentielles Backoff
Reduzieren Sie die Anzahl der Requests
Nutzen Sie Batch-Operationen wo möglich

Weiterführende Ressourcen

Token widerrufen

Falls Sie den Zugriff widerrufen müssen:

Navigieren Sie zu: Einstellungen → Integrationen → Private Apps
Wählen Sie Ihre App aus
Klicken Sie auf "App löschen" oder generieren Sie einen neuen Token

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