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

Ein HubSpot-Konto (Professional oder Enterprise)
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

Token-Verwaltung: Speichere Deinen Access Token niemals im Code
Regelmäßige Rotation: Erneuere Tokens regelmäßig
Minimale Berechtigungen: Aktiviere nur benötigte Scopes
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

Token widerrufen

Falls Du den Zugriff widerrufen musst:

Navigiere zu: Einstellungen → Integrationen → Private Apps
Wähle Deine App aus
Klicke auf "App löschen" oder generiere einen neuen Token

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