KI-Agent an HubSpot anbinden: API, MCP und Breeze
HubSpot ist für viele Vertriebs- und Serviceteams das System, in dem Kontakte, Firmen, Deals und Tickets liegen. Ein KI-Agent, der Angebote vorbereitet, Gesprächsnotizen ablegt oder Deals pflegt, braucht deshalb Lese- und oft auch Schreibzugriff auf dieses CRM. Dafür gibt es drei Wege: die REST-API, den offiziellen MCP-Server und HubSpots eigene Agenten unter dem Namen Breeze. Alle Angaben beziehen sich auf die HubSpot-Dokumentation, Stand November 2026.
Was bedeutet es, einen KI-Agenten an HubSpot anzubinden?
Anbinden heißt: Der Agent kann Datensätze in HubSpot gezielt suchen, lesen, anlegen und ändern, und zwar über definierte Werkzeuge mit klar begrenzten Rechten. Er arbeitet nicht mit einer Kopie, sondern mit dem aktuellen Stand im CRM.
Typische Aufgaben, für die ein Agent HubSpot-Zugriff braucht:
- Vorbereitung: vor einem Termin alle Kontakte, offenen Deals, letzten E-Mails und Notizen zu einer Firma zusammenfassen.
- Nachbereitung: aus einem Gesprächsprotokoll eine Notiz am Kontakt anlegen, eine Aufgabe für den Follow-up erzeugen und die Deal-Phase vorschlagen.
- Datenpflege: Dubletten erkennen, fehlende Pflichtfelder an Deals melden, verwaiste Kontakte ohne Firmenzuordnung finden.
- Service: zu einem Ticket die Vorgeschichte des Kunden und verwandte Tickets heraussuchen.
Der Unterschied zu einer klassischen Integration: Eine Integration synchronisiert fest definierte Felder. Ein Agent entscheidet im Lauf, welche Daten er braucht, und kombiniert HubSpot mit anderen Quellen. Das macht ihn flexibel, verlangt aber strengere Grenzen bei Rechten und Schreibzugriff.
Wie funktioniert der Zugriff technisch? Die Bausteine
Der Zugriff besteht aus vier Bausteinen: einer Authentifizierung, den CRM-Objekten mit ihren Properties, den Associations zwischen Objekten und den Limits der API. Wer diese vier versteht, kann jede der drei Varianten bewerten.
Authentifizierung: Service Key, App oder Legacy Private App
Hier hat sich im Herbst 2026 etwas Wesentliches geändert. Laut HubSpot-Dokumentation zu Legacy Private Apps lassen sich diese seit dem 26. Oktober 2026 nicht mehr neu erstellen. Bestehende Private Apps funktionieren weiter, erhalten aber keine neuen Funktionen. Viele ältere Anleitungen im Netz beschreiben noch diesen Weg.
Für neue Anbindungen gibt es zwei Optionen:
- Service Key: Ein Schlüssel für direkte REST-Aufrufe, den Super-Admins und Nutzer mit der Berechtigung für Entwicklerwerkzeuge anlegen. Er erhält objektbezogene Scopes wie
crm.objects.contacts.readund wird als Bearer-Token imAuthorization-Header gesendet. Laut HubSpot zu Service Keys unterstützen sie nur REST-Anfragen, keine Webhooks. Eine automatische Rotation alle 3, 6 oder 12 Monate lässt sich einschalten. - App auf der Developer Platform: Apps der Versionen 2025.2, 2026.03 und 2026.09 werden laut HubSpot-Übersicht über die HubSpot CLI angelegt (
hs project create) und bereitgestellt. Sie nutzen ein statisches Token oder OAuth und sind nötig, sobald Sie Webhooks oder weitere Plattformfunktionen brauchen.
Für einen Agenten, der in einem einzigen HubSpot-Konto liest und schreibt, ist ein Service Key der einfachste Einstieg. Soll der Agent auf Ereignisse reagieren, etwa auf einen neuen Deal, brauchen Sie eine App mit Webhooks.
CRM-Objekte und Properties
Alles in HubSpot ist ein Objekt: Kontakte, Firmen, Deals, Tickets, dazu Aktivitäten wie Notizen, Aufgaben, Anrufe und Meetings sowie eigene Custom Objects. Jedes Objekt hat Properties, also Felder. Für den Agenten ist entscheidend, welche Properties es gibt und was sie bedeuten. Ein Feld lifecyclestage oder eine eigene Property „Angebotsstatus" ist für das Modell nur nutzbar, wenn die erlaubten Werte bekannt sind. Geben Sie dem Agenten deshalb eine kurze Beschreibung der wichtigen Properties mit, statt ihn raten zu lassen.
Associations: wie Datensätze zusammenhängen
Associations verknüpfen Datensätze, etwa einen Kontakt mit seiner Firma oder einen Deal mit den beteiligten Kontakten. Laut HubSpot-Leitfaden zu Associations gibt es unbeschriftete Standardverknüpfungen, von HubSpot definierte Labels wie „Primary company" und eigene Labels wie „Entscheider". Jede Richtung hat eine eigene Typ-ID: Kontakt zu Firma ist 279, Kontakt zu primärer Firma ist 1, Deal zu Kontakt ist 3, Kontakt zu Deal ist 4.
Für Agenten ist das ein häufiger Fehlerpunkt. Legt ein Agent eine Notiz an, ohne sie mit Kontakt und Deal zu verknüpfen, taucht sie in keiner Zeitleiste auf. Das Werkzeug „Notiz anlegen" sollte die Verknüpfung deshalb immer mit erledigen, statt sie dem Modell als separaten Schritt zu überlassen. Batch-Endpunkte erlauben laut HubSpot bis zu 1.000 Eingaben beim Lesen und bis zu 2.000 beim Anlegen.
Suche, Limits und Versionen
Die CRM-Suche ist das wichtigste Werkzeug eines Agenten, hat aber enge Grenzen. Laut HubSpot-Leitfaden zur Suche gilt: fünf Anfragen pro Sekunde und Konto, maximal 200 Ergebnisse pro Seite, höchstens 10.000 Ergebnisse je Abfrage, bis zu fünf Filtergruppen mit insgesamt 18 Filtern. Neu angelegte oder geänderte Datensätze erscheinen erst nach kurzer Verzögerung in der Suche.
Die allgemeinen Limits für privat verteilte Apps nennt HubSpot in den Nutzungsrichtlinien: 100 Anfragen pro 10 Sekunden in Free und Starter, 190 in Professional und Enterprise, dazu Tageslimits je Konto. Bei Überschreitung antwortet die API mit Status 429.
Seit März 2026 versioniert HubSpot seine APIs nach Datum. Laut Changelog erscheinen neue Versionen im März und September, jede wird mindestens 18 Monate unterstützt, und die v4-APIs nur noch bis März 2027. Eine neue Anbindung sollte deshalb direkt auf /2026-09/ aufsetzen.
Ein Suchwerkzeug für den Agenten kann so aussehen (Python 3 mit der Bibliothek requests, Endpunkt nach dem Suchleitfaden):
import os
import requests
BASE = "https://api.hubapi.com/crm/objects/2026-09"
HEADERS = {"Authorization": f"Bearer {os.environ['HUBSPOT_SERVICE_KEY']}"}
def deals_einer_firma(firmen_id: str) -> list[dict]:
"""Werkzeug für den Agenten: Deals, die mit einer Firma verknüpft sind."""
body = {
"filterGroups": [{
"filters": [
{"propertyName": "associations.company", "operator": "EQ", "value": firmen_id},
]
}],
"properties": ["dealname", "dealstage", "amount", "closedate"],
"limit": 50,
}
r = requests.post(f"{BASE}/deals/search", json=body, headers=HEADERS, timeout=20)
r.raise_for_status()
return [d["properties"] for d in r.json().get("results", [])]
Die Deal-Phase in dealstage wertet der Agent danach selbst aus. Das Werkzeug gibt nur die Felder zurück, die der Agent für seine Aufgabe braucht. Das hält den Kontext klein und verhindert, dass vertrauliche Properties unnötig im Modell landen.
Welche Varianten gibt es? API, MCP und Breeze im Vergleich
Es gibt drei Varianten: eigene Werkzeuge auf der REST-API, den offiziellen Remote-MCP-Server von HubSpot und HubSpots eigene Agenten (Breeze). Sie unterscheiden sich darin, wer die Logik kontrolliert, welches Modell arbeitet und wie fein Sie Rechte steuern können.
| Kriterium | Eigene API-Werkzeuge | HubSpot-MCP-Server | Breeze-Agenten |
|---|---|---|---|
| Wer baut die Werkzeuge | Sie | HubSpot | HubSpot |
| Modell | frei wählbar | MCP-fähiger Client | HubSpot |
| Rechte | Scopes des Keys | Rechte des Nutzers | HubSpot-Rollen |
| Andere Systeme einbinden | ja | über weitere MCP-Server | eingeschränkt |
| Hosting | bei Ihnen | bei HubSpot | bei HubSpot |
Variante 1: eigene Werkzeuge auf der REST-API
Sie schreiben Funktionen wie „Deals einer Firma suchen" oder „Notiz anlegen und verknüpfen" und geben sie dem Agenten als Werkzeuge. Das ist der meiste Aufwand, aber auch die meiste Kontrolle: Sie legen fest, welche Felder gelesen werden, welche Schreibvorgänge erlaubt sind und was protokolliert wird. Das Muster ist dasselbe wie bei anderen Systemen, siehe KI-Agenten an Unternehmenssysteme anbinden. Diese Variante passt, wenn der Agent HubSpot mit ERP, Ticketsystem oder Dateiablage kombiniert oder wenn das Modell lokal oder bei einem bestimmten Anbieter laufen soll.
Variante 2: der offizielle HubSpot-MCP-Server
HubSpot betreibt einen Remote-MCP-Server unter https://mcp.hubspot.com. Laut HubSpot-Dokumentation legen Sie dafür in HubSpot unter Development einen MCP Connector an, erhalten Client-ID und Secret, und der MCP-Client übernimmt die OAuth-Anmeldung; PKCE ist Pflicht. Scopes definieren Sie nicht selbst, der Zugriff folgt den Rechten des Nutzers, der den Connector installiert.
Lesen kann der Server unter anderem CRM-Datensätze, Aktivitäten, Marketing-Inhalte und Konversationen; schreiben unter anderem CRM-Datensätze, Aktivitäten, Pipelines und eigene Properties. Umsatzobjekte wie Angebote und Rechnungen sind laut HubSpot im Beta-Status. Die Dokumentation nennt auch Grenzen: Das Abfragewerkzeug kennt keine Joins und kein Durchlaufen von Associations, und bei aktivierter Einstellung für sensible Daten sind Konversationen und Aktivitäten gesperrt.
Wie MCP-Server allgemein funktionieren und worauf Sie bei fremden Servern achten, beschreibt der Leitfaden MCP-Server für KI-Agenten.
Davon zu trennen ist der Developer-MCP-Server, den die HubSpot CLI lokal startet (hs mcp setup). Laut HubSpot-MCP-Übersicht hilft er Coding-Assistenten beim Bau von Apps und CMS-Inhalten, nicht beim Zugriff auf CRM-Daten.
Variante 3: Breeze, HubSpots eigene Agenten
Breeze ist die KI-Schicht innerhalb von HubSpot. Die HubSpot-Produktseite nennt unter anderem einen Prospecting Agent, einen Customer Agent, einen Data Agent und einen Agent Builder für eigene Agenten auf HubSpot-Daten. Laut HubSpot Knowledge Base werden die Agenten im Agent Hub verwaltet und benötigen HubSpot Credits; einige setzen Professional- oder Enterprise-Abos voraus.
Breeze passt, wenn die Aufgabe vollständig in HubSpot liegt und Sie keine eigene Logik und kein eigenes Modell brauchen. Ein eigener Agent passt, wenn er Daten außerhalb von HubSpot einbezieht, wenn Sie das Modell selbst wählen wollen oder wenn die Abläufe über mehrere Systeme hinweg dokumentiert und versioniert werden müssen. Beides schließt sich nicht aus: Breeze im Service, ein eigener Agent für die Angebotsvorbereitung mit ERP-Daten.
Welche Voraussetzungen brauchen Sie?
Sie brauchen drei Dinge: einen gepflegten Datenbestand, eine Person mit Admin- oder Entwicklerrechten in HubSpot und eine klare Festlegung, was der Agent ändern darf. Ohne diese Punkte erzeugt ein Agent eher Mehrarbeit als Entlastung.
Daten: Sind Kontakte ihren Firmen zugeordnet? Gibt es Dubletten? Sind Deal-Phasen und Pflichtfelder einheitlich gepflegt? Ein Agent arbeitet nur so gut wie die Associations und Properties, auf die er sich stützt.
Rechte: Service Keys legen Super-Admins oder Nutzer mit Entwicklerberechtigung an. Beim MCP-Server erbt der Agent die Rechte des installierenden Nutzers. Ein eigener technischer Nutzer mit eng gefasster Rolle ist meist besser als der Zugang einer Führungskraft mit Vollzugriff.
Organisation: Legen Sie fest, wer Ergebnisse des Agenten prüft, wer bei Fehlern angesprochen wird und welche Felder grundsätzlich nur Menschen ändern, etwa Deal-Betrag oder Abschlussdatum. Wenn personenbezogene Daten an ein externes Modell gehen, ist das ein Datenschutzthema; ein Setup ist datenschutzkonform betreibbar, verlangt aber Auftragsverarbeitung, Löschkonzept und Protokollierung. Das ist eine Orientierung, keine Rechtsberatung.
Wie gehen Sie in Schritten vor?
Beginnen Sie lesend mit einem eng umrissenen Ablauf, messen Sie die Qualität an echten Fällen und schalten Sie Schreibrechte erst danach Feld für Feld frei. So bleibt jeder Schritt überprüfbar.
- Ablauf wählen: ein Prozess mit klarem Anfang und Ende, etwa „Terminvorbereitung für Bestandskunden".
- Datenquellen festlegen: welche Objekte, welche Properties, welche Associations. Alles andere bleibt außen vor.
- Zugang anlegen: Service Key mit reinen Lese-Scopes oder MCP Connector mit einem technischen Nutzer.
- Werkzeuge bauen oder auswählen: bei der API eigene Funktionen mit festen Feldlisten, beim MCP-Server die benötigten Werkzeuge im Client freigeben.
- Testen mit echten Fällen: zehn bis zwanzig reale Vorgänge durchspielen und die Ergebnisse mit dem vergleichen, was ein erfahrener Mitarbeiter liefern würde.
- Schreibrechte schrittweise: zuerst Notizen und Aufgaben, die niemandem schaden, später Felder an Deals, jeweils mit Protokoll.
- Betrieb: Fehler und
429-Antworten überwachen, Schlüssel rotieren, API-Version vor Ablauf des Supportzeitraums wechseln.
Wo liegen Grenzen und Risiken?
Die größten Risiken sind falsche Schreibvorgänge, zu weite Rechte und manipulierte Inhalte im CRM. Hinzu kommen technische Grenzen der Suche und der API-Versionen, die ein Agent im Dauerbetrieb früher oder später erreicht.
- Prompt Injection über CRM-Inhalte: E-Mails, Formulareinträge und Notizen stammen teils von außen. Steht darin eine Anweisung an „die KI", kann ein Agent sie befolgen (Prompt Injection). Schreibende Werkzeuge brauchen deshalb harte Grenzen im Code, nicht nur im Prompt.
- Zu weite Rechte: Beim MCP-Server hat der Agent die Rechte des Nutzers. Installiert ein Super-Admin den Connector, kann der Agent sehr viel.
- Suchverzögerung: Ein Agent, der einen Kontakt anlegt und ihn sofort wieder sucht, findet ihn eventuell nicht und legt eine Dublette an. Arbeiten Sie nach dem Anlegen mit der zurückgegebenen ID.
- Mengengrenzen: fünf Suchanfragen pro Sekunde und 10.000 Ergebnisse je Abfrage reichen für Einzelfälle, nicht für Auswertungen über den ganzen Bestand. Dafür sind Exporte oder ein Data Warehouse geeigneter.
- Versionen und Plattformwechsel: Legacy Private Apps sind eingefroren, v4-APIs laufen im März 2027 aus. Planen Sie Wartung ein.
- Wann es nicht passt: Wenn das CRM kaum gepflegt ist oder der Prozess selbst unklar ist, löst ein Agent das Problem nicht, sondern macht es sichtbar.
Wie fangen Sie an?
Starten Sie mit einem Service Key mit reinen Lese-Scopes und einem einzigen Werkzeug, etwa der Deal-Suche oben, oder verbinden Sie zum Ausprobieren einen MCP-fähigen Client mit dem HubSpot-MCP-Server. Nach den ersten echten Fällen sehen Sie, welche Daten fehlen und welche Schreibrechte sich lohnen.
In unserem eigenen Betrieb hat sich bewährt, den Agenten zuerst nur Vorschläge schreiben zu lassen, die ein Mensch übernimmt. Welche Aufgaben ein Sales-Agent im Vertrieb übernehmen kann, steht im gleichnamigen Leitfaden. Arbeitet Ihr Vertrieb statt mit HubSpot mit Microsoft, ändern sich vor allem Authentifizierung und Datenmodell; das beschreibt der Artikel KI-Agent an Dynamics 365 anbinden. Wie solche Agenten im Vertrieb aufgebaut sind, beschreibt die Seite zum Vertriebs-Agenten; einen Überblick über KI-Agenten für Unternehmensprozesse finden Sie dort ebenfalls. Wenn Modell und Daten im eigenen Haus bleiben sollen, lohnt ein Blick auf souveräne KI.
Häufige Fragen
Kann ich noch eine klassische Private App in HubSpot anlegen?
Nein. Laut HubSpot-Dokumentation lassen sich Legacy Private Apps seit dem 26. Oktober 2026 nicht mehr neu erstellen; bestehende laufen weiter. Für neue Anbindungen nutzen Sie einen Service Key oder eine App auf der Developer Platform.
Braucht der HubSpot-MCP-Server ein eigenes Hosting?
Nein, der Server läuft bei HubSpot unter mcp.hubspot.com. Sie legen in HubSpot einen MCP Connector an und Ihr MCP-Client übernimmt die OAuth-Anmeldung mit PKCE.
Ersetzt Breeze einen eigenen Agenten?
Für Standardaufgaben innerhalb von HubSpot oft ja. Sobald der Agent Daten aus ERP, Ticketsystem oder Dokumentenablage zusammenführen oder ein bestimmtes Modell nutzen soll, ist ein eigener Agent mit API- oder MCP-Zugang die flexiblere Wahl.
Welche API-Version sollte eine neue Anbindung verwenden?
HubSpot empfiehlt für neue Integrationen die jeweils neueste datumsbasierte Version, derzeit /2026-09/. Die v4-APIs werden laut HubSpot nur noch bis März 2027 unterstützt.
Quellen
- HubSpot Developers: Legacy private apps developers.hubspot.com
- HubSpot Developers: Service keys developers.hubspot.com
- HubSpot Developers: Build apps – Overview developers.hubspot.com
- HubSpot Developers: Integrate with the HubSpot MCP server developers.hubspot.com
- HubSpot Developers: MCP developers.hubspot.com
- HubSpot Developers: Associations guide developers.hubspot.com
- HubSpot Developers: CRM search guide developers.hubspot.com
- HubSpot Developers: API usage guidelines and limits developers.hubspot.com
- HubSpot Developer Changelog: Introducing date-based API versioning developers.hubspot.com
- HubSpot Knowledge Base: Agent Hub und Agenten knowledge.hubspot.com
- HubSpot: AI-Produktseite hubspot.com