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
crm.objects.deals.write – Deals erstellen/aktualisieren
crm.objects.owners.read – Eigentümer-Informationen lesen

Weitere Berechtigungen:

conversations.read – Konversationen und Nachrichten lesen
files – Dateien lesen/suchen und Signed URLs abrufen

Optional / Erweiterte Objekt-Scopes (für generische CRM-Suche):

sales-email-read (für E-Mail-Objekt-Endpunkte)
Für weitere Objektfamilien (notes, tasks, calls, meetings) die jeweiligen Endpoint-Dokumentationen von HubSpot prüfen.

Je nach HubSpot-Setup zusätzlich erforderlich:

Ticket-bezogene Scopes für Ticket-Endpunkte (hubspot_get_tickets, hubspot_get_ticket_conversation_threads, pipelines/tickets)

Scope-Profile (Wann brauche ich welche Scopes?)

Use Case	Benötigte Scopes
Basis CRM Read (Owner + Suche/Abruf für Kontakte/Unternehmen/Deals)	`crm.objects.owners.read`, `crm.objects.contacts.read`, `crm.objects.companies.read`, `crm.objects.deals.read`
CRM Write (Kontakt/Unternehmen/Deal erstellen)	`crm.objects.contacts.write`, `crm.objects.companies.write`, `crm.objects.deals.write`
Konversationen (`hubspot_get_recent_conversations`)	`conversations.read`
Dateien (`hubspot_search_files`, `hubspot_get_file`)	`files`
Ticket-Workflows (`hubspot_get_tickets`, Ticket-Pipelines/Threads)	`tickets` (abhängig von Account/Feature)
Generische Suche für weitere Objekte	objekt-spezifische Scopes aus der jeweiligen HubSpot-Endpoint-Doku (für E-Mails: `sales-email-read`)

Methode-zu-Scope-Mapping

Methode	Scopes
`hubspot_get_owners`	`crm.objects.owners.read`
`hubspot_get_active_contacts`	`crm.objects.contacts.read`
`hubspot_create_contact`	`crm.objects.contacts.write`
`hubspot_get_active_companies`	`crm.objects.companies.read`
`hubspot_create_company`	`crm.objects.companies.write`
`hubspot_get_deals`	`crm.objects.deals.read`
`hubspot_create_deal`	`crm.objects.deals.write`
`hubspot_search_crm_objects`	objekt-spezifische Scopes aus Endpoint-Doku (für `emails`: `sales-email-read`)
`hubspot_retrieve_crm_object`	objekt-spezifische Scopes aus Endpoint-Doku
`hubspot_get_recent_conversations`	`conversations.read`
`hubspot_search_files`	`files`
`hubspot_get_file`	`files`
`hubspot_get_tickets`, `hubspot_get_ticket_conversation_threads`, Ticket-Pipelines	`tickets` (abhängig von HubSpot-Setup)

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

Generische Suche & Retrieve

hubspot_search_crm_objects: Generische CRM-Suche (Kontakte, Unternehmen, Deals, Notizen, Tasks, Calls, Meetings, E-Mails)
hubspot_retrieve_crm_object: Einzelnes CRM-Objekt per ID abrufen, optional mit Associations

Dateizugriff

hubspot_search_files: HubSpot-Dateien (Metadaten) durchsuchen
hubspot_get_file: Datei-Metadaten und Signed URL abrufen

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

CRM-Objekt abrufen

Suche den neuesten Deal der Firma "Beispiel GmbH" und lade danach die Deal-Details per ID

Dateien suchen und laden

Suche in HubSpot-Dateien nach "Rechnung" und gib mir die Signed Download-URL des neuesten Treffers

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
Bei Scope-Fehlern den Debug-Output des Connectors (requiredScopes) prüfen und fehlende Scopes ergänzen

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.

HubSpot Integration

Auf dieser Seite